Documentação / Webhooks

Webhooks

Receba eventos do WhatsApp (conexão do número, entrada em grupos) no seu endpoint em tempo real — pra alimentar o seu sistema, o Make ou o n8n.

Configurar o endpoint

Aponte a sua URL para uma instância. O corpo é processado pela API.

POST/v1/instances/:instance/webhook

curl -X POST https://dashboard.vistoazul.com.br/api/v1/instances/vendas/webhook \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://seu-sistema.com/webhook","enabled":true}'

Mais simples ainda: dá pra colar a URL do seu fluxo Make/n8n direto no painel, sem código. No n8n, o node oficial da Visto Azul tem um gatilho que registra esse webhook sozinho.

Formato dos eventos

Cada evento chega como POST JSON no seu endpoint, no formato:

{
  "EventType": "groups",
  "event": { ... },
  "instanceName": "vendas",
  "owner": "5511999999999"
}

Evento `connection`

Disparado quando o número conecta ou cai. Útil pra avisar você se uma instância desconectar.

Evento `groups`

Disparado quando alguém entra ou sai de um grupo seu (ex.: via link de funil).

{
  "EventType": "groups",
  "event": {
    "JID": "1203...@g.us",
    "Join": ["5511999999999@s.whatsapp.net"],
    "Leave": null,
    "JoinReason": "invite"
  },
  "instanceName": "vendas"
}

Campo	Descrição
`JID`	Grupo onde ocorreu o evento.
`Join`	Lista de quem entrou (vazio/null se ninguém).
`Leave`	Lista de quem saiu.
`JoinReason`	Como entrou — ex.: `invite` (pelo link).

Privacidade (LGPD): por padrão, o webhook entrega só eventos de conexão e de grupos — não o conteúdo de conversas privadas. Trate qualquer dado recebido conforme a sua política de privacidade.

Recebeu áudio, imagem ou documento?

Quando chega uma mensagem de mídia, o webhook traz o id dela. Com esse id você baixa o arquivo (em base64) — e áudio ainda pode vir transcrito:

POST/v1/messages/media

curl -X POST https://dashboard.vistoazul.com.br/api/v1/messages/media \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instance":"vendas","id":"ID_DA_MENSAGEM","transcribe":true}'

Resposta: { "base64", "mimetype", "transcription" }. O base64 é o próprio arquivo (áudio volta como MP3). Veja também as outras ações de atendimento (marcar como lida, "digitando…", reagir, editar, apagar).

Áudio no n8n? O campo base64 é o arquivo. Para virar um arquivo binário no fluxo, use um nó Convert to File (base64 → binary) — igual você faz com imagem. Se você só quer o conteúdo do áudio em texto, mande "transcribe": true e use o campo transcription direto.

Dica de integração

Combine com a API: ao receber um groups → Join, dispare uma mensagem de boas-vindas com /v1/messages/text, ou registre o lead no seu CRM. Webhook de entrada + envio = automação completa.

Anterior← Grupos & Funil PróximoReferência da API →