Webhooks

Configurar

No painel, menu Integrações → Webhooks (dono ou administrador da agência, com a verificação em duas etapas). Cada webhook tem:

• a URL (HTTPS, num endereço público);
• os eventos que ele quer receber;
• o escopo: todos os chatbots da agência, os de um cliente ou chatbots escolhidos;
• cabeçalhos personalizados (opcional, até 10, guardados cifrados);
• o segredo (whsec_…), mostrado uma vez ao criar.

Enviar teste manda um webhook.test assinado. Em Logs aparecem as entregas, com o corpo e a sua resposta; Reenviar falhas desde põe de volta na fila o que falhou a partir de uma data.

O envelope

Todo evento chega no mesmo formato. O que muda de um evento para outro é o data.

{
  "id": "evt_k3x2f7…",
  "type": "message.received",
  "created_at": "2026-10-15T19:02:11.482Z",
  "bot": { "id": "bot_8c1e…", "name": "Bar do Zé" },
  "client": { "id": "cli_51a0…", "external_id": null },
  "conversation": { "id": "conv_14a2…", "channel": "whatsapp" },
  "contact": {
    "id": "ctc_77d0…",
    "whatsapp_user_id": null,
    "phone": "5511999990000",
    "instagram_id": null,
    "display": { "name": "Ruan" }
  },
  "data": {
    "message": {
      "id": "msg_48213",
      "text": "Pedir este: Pizza Calabresa",
      "media": null,
      "interactive": { "type": "button_reply", "id": "pedir_101", "title": "Pedir este" }
    }
  }
}

Eventos

Mensagens

Arquivo na mensagem: media traz {id, type, mime, size, filename, transcript, reading, url, url_expires_at}. O url vale 1 hora (é gerado de novo a cada tentativa); depois, baixe por GET /v1/media/{id}. Áudio vem com a transcrição; foto que a IA leu vem com reading, o que ela entendeu da foto (veja em Arquivos e fotos).

Atendimento

Chamados

Para quem já tem um helpdesk (Zendesk, Freshdesk…): o ticket.created leva o necessário para criar o chamado lá, com o protocolo do BoaVoz como referência; o ticket.updated mantém os dois iguais.

Roteiros

Contato

Campanhas, canais e conformidade

Cota, excedente e crédito

Todos trazem o uso do mês no data: month, used (dentro da cota), quota e overage {enabled, used, cap_brl, max, value_brl}. Cada aviso sai uma vez por mês e chatbot.

Receber e conferir

O BoaVoz faz um POST com o envelope, assinado no padrão Standard Webhooks com o segredo do webhook: cabeçalhos webhook-id (o id do evento), webhook-timestamp e webhook-signature. Confira com a biblioteca oficial e responda 2xx rápido.

// npm i express standardwebhooks
import express from "express";
import { Webhook } from "standardwebhooks";

const app = express();
const wh = new Webhook(process.env.BOAVOZ_WEBHOOK_SECRET); // whsec_... do webhook

app.post("/boavoz/eventos", express.text({ type: "*/*" }), async (req, res) => {
  let evento;
  try {
    evento = wh.verify(req.body, req.headers); // assinatura e horário (até 5 minutos)
  } catch {
    return res.status(401).end();
  }
  // a nova tentativa traz o mesmo id: processe uma vez só
  if (await jaProcessado(evento.id)) return res.status(200).end();
  await fila.publicar(evento); // responda rápido; o trabalho pesado vai para a sua fila
  res.status(200).end();
});

Entrega e novas tentativas

• Entregue = 2xx em até 10 segundos. Qualquer outra coisa conta como falha.
• Novas tentativas, com o mesmo id: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h e 24 h depois (9 tentativas no total). Cada tentativa vai com horário e assinatura novos.
• 410 Gone desativa o webhook na hora. 3 dias seguidos só de falhas também desativam. O dono da conta recebe um e-mail com 1 hora de falhas, outro no segundo dia e outro quando o webhook é desativado, com o link para reativar. O painel mostra o motivo; reative e use “Reenviar falhas desde” para recuperar o que ficou para trás.
• Até 10 entregas ao mesmo tempo por webhook: a partir da 11ª, o evento espera na fila e sai no minuto seguinte, na ordem. Os eventos de alto volume (message.status e os envios de campanha) sempre saem pela fila.
• Um pedido do titular (LGPD) apaga as entregas do contato, inclusive as pendentes, antes do contact.deleted.

Para testar sem servidor, use o Svix Play: ele mostra os eventos com os cabeçalhos e o corpo. Veja também Ações, que usam a mesma assinatura.