Webhooks de WhatsApp

Reencaminhar as mensagens e estados do WhatsApp para um URL próprio, de imediato, com espera ou por intervalos.

Categoria: Comunicação
Estado: Disponível
Requisitos: Uma conta de WhatsApp na empresa; Um URL que aceite POST com JSON
Ferramentas MCP (Só leem): listar_numeros_whatsapp
Ferramentas MCP (Escrevem ou modificam): crear_webhook_whatsapp, editar_webhook_whatsapp, simular_mensaje_sandbox_whatsapp
Ferramentas MCP (Destrutivas): eliminar_webhook_whatsapp

O que permite fazer?

Configurar um ou vários URLs que recebem as mensagens recebidas e as mudanças de estado de todos os números da conta. É a peça que liga o WhatsApp a um bot próprio.

Quando convém usar?

Um bot tem de responder a mensagens.
Outro sistema precisa de registrar as conversas.
Quer agrupar várias mensagens seguidas de um contato antes de as processar.

Como funciona na ArduMaker?

Modo	Quando envia
`instant`	Assim que a mensagem está pronta. Um áudio sai quando termina a transcrição.
`debounce`	Depois de `debounce_seconds` sem mensagens novas nesse chat (0 a 3600, 10 por omissão).
`interval`	A cada `interval_seconds`, com todos os chats pendentes (0 a 86400, 60 por omissão).

O corpo é um JSON com a conta, o modo e uma lista de conversas (headers) com as suas mensagens. Os arquivos chegam como URL público assinado; o caminho interno do arquivo nunca é enviado. send_incoming e send_status escolhem o que se envia.

Com notify_audio_received o webhook recebe de imediato um aviso com "event": "audio_received" e o cabeçalho X-Event: audio_received, antes da transcrição. A mensagem definitiva sai depois, sem event.

O que muda realmente?

A configuração do webhook é guardada na conta de WhatsApp da empresa.
Cada entrega fica registrada por mensagem, com o código HTTP, a duração e a espera da plataforma.
Uma mensagem de teste acrescenta "sandbox": true e o cabeçalho X-Sandbox: 1; um reenvio manual acrescenta "resend": true.

Esquema

WhatsApp
Twilio: avisa a ArduMaker
ArduMaker: guarda e transcreve se for áudio
Entrega conforme o modo: instant, debounce ou interval
O seu URL: POST com JSON

Mensagem recebida até ao webhook — Em instant a entrega sai de imediato; uma varredura periódica é a rede de segurança e nunca envia a mesma mensagem duas vezes.

Resultado esperado

O seu servidor recebe cada mensagem uma vez. No chat vê-se quanto demorou cada entrega e que código o webhook devolveu.

Erros e resolução

O webhook estava em baixo: a entrega automática não repete. No chat, uma mensagem concreta pode ser reenviada aos webhooks; o reenvio não altera o que está pendente.
Áudio contado duas vezes: o aviso audio_received e a mensagem final são dois POST; é preciso distingui-los por event.
400 `invalid_data`: algum campo é inválido; a resposta indica quais.
Porque é que o meu webhook recusa algo: o sandbox devolve o código e o corpo com que cada webhook respondeu.

Relação com MCP

Requer acesso à empresa. Ver /mcp/docs.

Tipo	Ferramentas
Leitura	`listar_numeros_whatsapp`
Modificam	`crear_webhook_whatsapp`, `editar_webhook_whatsapp`, `simular_mensaje_sandbox_whatsapp`
Destrutiva	`eliminar_webhook_whatsapp`