Pular para o conteúdo principal
Em vez de fazer polling na API em busca de novas atividades, você pode configurar o PanÐá Zap para enviar eventos ao seu servidor no momento em que algo acontece: uma nova mensagem chega, um canal, usuário ou API é criado ou atualizado, ou uma mensagem enviada pelo WhatsApp oficial é entregue, lida ou falha. Isso é chamado de webhook.

Como os webhooks funcionam

Quando um evento de disparo ocorre, o PanÐá Zap envia uma requisição HTTP POST para a URL que você configurou. Seu servidor deve responder com um código de status 2xx. Atualmente, o PanÐá Zap não tenta reenviar entregas que falharam, então garanta que seu endpoint seja confiável e responda rapidamente. Existem dois tipos de webhooks:

Configurar um webhook de canal


Payload de evento de mensagem

Quando uma mensagem chega em um canal com webhooks ativados, o PanÐá Zap envia um payload semelhante ao seguinte:
ticket.id está sempre presente no payload do webhook para todos os tipos de canal: WhatsApp, Instagram, Messenger, Telegram e e-mail. Você sempre pode usá-lo para correlacionar o evento com um registro de ticket através da API de Tickets.

Configurar webhooks globais

Os webhooks globais permitem que você assine múltiplos tipos de evento em toda a sua conta, não apenas em um canal.
  1. No menu Configuração, abra Configurações, vá para a aba Integrações e clique em Webhooks.
  2. Em Webhook principal, ative Ativar webhook e preencha a URL do Webhook.
  3. Ative Webhook mensagens para receber os eventos de mensagem.
  4. Para receber o status das mensagens enviadas pelo WhatsApp oficial (enviada, entregue, lida, falhou), ative Webhook status de envio. Veja Status de envio das mensagens.
  5. Em Eventos de canal e usuário, ative só os eventos de que você precisa.
  6. Clique em Salvar.
Eventos disponíveis na tela:
Assine apenas os eventos que você realmente utiliza. Toda chamada de webhook adiciona carga ao seu servidor: eventos desnecessários desperdiçam largura de banda e aumentam o overhead de processamento.

Status de envio das mensagens

Com Webhook status de envio ligado (em Configuração → Configurações → aba Integrações → Webhooks, junto da URL do Webhook), o PanÐá Zap avisa o seu sistema quando cada mensagem enviada é aceita, entregue, lida ou falha, com o motivo do erro.
  • Por enquanto, vale só para o WhatsApp oficial direto.
  • Cada mensagem enviada gera até 3 avisos, inclusive as de campanha.
  • Os avisos podem chegar fora de ordem: use o horário de cada um para ordenar.
  • Se o seu endereço não responder em 10 segundos, o aviso não é reenviado. Se ele demorar a responder e os avisos acumularem, os excedentes são descartados.

Segurança

As URLs de webhook devem ser publicamente acessíveis via HTTPS. Por padrão, o PanÐá Zap não envia um cabeçalho de assinatura. Para proteger seu endpoint:
  • Restringir por IP: configure seu servidor ou firewall para aceitar apenas requisições POST vindas dos endereços IP de saída do PanÐá Zap.
  • Token secreto na URL: incorpore um token longo e aleatório no caminho da URL ou como um parâmetro de consulta (por exemplo, https://seuservidor.com.br/webhooks/pandazap?token=abc123). Verifique sua presença em toda requisição recebida.

Alternativa de polling

Se sua infraestrutura não pode expor um endpoint HTTPS público, você pode fazer polling na API periodicamente:
No showAllMessages, o ID do atendimento vai no corpo, no campo ticket (ou em ticketId, com o mesmo valor). Sem o ID, a rota responde 400 com ERR_MISSING_TICKET.
O showAllMessages devolve também as mensagens de sistema do atendimento, que nunca foram enviadas ao contato: notas internas (mediaType notes ou callNotes) e divisórias de transferência (mediaType transfer), registradas quando o atendimento muda de fila, de atendente, de fluxo ou de canal. Quem lê o histórico para responder ou para alimentar a sua integração não deve tratar esses itens como mensagens do cliente: filtre pelo mediaType. Veja o formato em Obter todas as mensagens de um ticket.
Faça polling em um intervalo razoável (por exemplo, a cada 30 a 60 segundos). listTickets e showAllMessages não têm limite por minuto, mas consultas muito frequentes geram carga desnecessária; para casos sensíveis à latência, prefira os webhooks.

Correlacionando eventos com seus registros

Inclua um externalKey único em toda requisição de API que envia uma mensagem. Quando o webhook de entrega disparar, o payload conterá o mesmo externalKey: use-o para relacionar o evento do webhook de volta ao registro de envio original no seu sistema, sem depender de IDs internos do PanÐá Zap.