# Webhooks de WhatsApp

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

Fonte: https://ardumaker.com/pt/docs/webhooks-whatsapp/

- Categoria: Comunicação
- Estado: Disponível
- Requisitos: Uma conta de [WhatsApp](https://ardumaker.com/pt/docs/whatsapp-business-api) 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

**Mensagem recebida até ao webhook**

```text
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)
```

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](https://ardumaker.com/pt/mcp/docs).

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

> **PRECAUCION:** Um webhook recebe tráfego real de clientes: quem muda o URL decide para onde vão as mensagens. Para o pausar, use `editar_webhook_whatsapp` com `is_active=false` em vez de o apagar.

## Funcionalidades relacionadas

- [WhatsApp Business API](https://ardumaker.com/pt/docs/whatsapp-business-api/)
- [Histórico de chats](https://ardumaker.com/pt/docs/historial-de-chats/)
- [Router IA](https://ardumaker.com/pt/docs/router-ia/)