Guias
Webhooks de canais e de agentes externos
Configure o contrato certo para receber mensagens de provedores ou entregar turnos ao seu chatbot.
Atualizado em
Dois caminhos de comunicação
O Interaflow recebe mensagens dos provedores de canal e pode enviar turnos da conversa ao webhook de um agente externo. Cada caminho tem configuração, autenticação e comportamento próprios.
| Caminho | Quem chama quem | Uso |
|---|---|---|
| Entrada de canal | Provedor → Interaflow | Receber mensagens e eventos do provedor configurado |
| Controle Externo | Interaflow → seu agente | Entregar contexto e receber ações de atendimento |
| Callback do agente | Seu agente → Interaflow | Concluir uma resposta assíncrona |
Webhooks de entrada dos canais
Configure o canal e use a URL indicada para a instância e o provedor. Os contratos de Gupshup, Zenvia, Meta e outros provedores diferem: tokens, verificações, assinatura e formato do evento devem seguir o guia correspondente.
A entrada normaliza os eventos para que a mensagem siga a rota da operação. Veja Canais antes de configurar uma URL no provedor.
Webhook de saída para seu agente
No nó Controle Externo, informe a URL HTTPS do agente e configure um segredo compartilhado. O Interaflow envia conversation.turn com mensagem, contato e histórico. O agente devolve ações como reply, handoff, end e wait.
Quando uma régua de inatividade estiver configurada, o mesmo endpoint também pode receber conversation.idle.
A assinatura, quando configurada, é enviada em X-Interaflow-Signature como HMAC-SHA256 do corpo cru. A configuração também pode repetir essa assinatura em um header adicional exigido pelo integrador.
Leia o contrato completo de agentes externos para implementar payload, validação da assinatura, ações, callback e diagnóstico.
Tratamento de falhas
No Controle Externo, timeout e respostas inválidas contam para o limite de falhas do nó. Configure a saída de erro e a fila de contingência. As tentativas podem ser consultadas em GET /api/v1/agent-deliveries.
Esse webhook não tem retry automático da mesma entrega. Não trate o protocolo como uma assinatura geral de todos os eventos da plataforma, nem presuma uma fila de reentrega para eventos de chamada.
Para extrair histórico de telefonia e URA, use a API de Integração.