> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blu.direct/llms.txt
> Use this file to discover all available pages before exploring further.

# Envie mensagens por webhook

> Envie mensagens de WhatsApp a partir do seu sistema, planilha ou automação usando a URL de webhook de um número.

Cada número conectado pode ter uma URL de webhook. Quando seu sistema faz uma requisição para essa URL, o blü envia a mensagem pelo WhatsApp desse número. Use para avisos de pedido, lembretes, confirmações de cadastro ou qualquer envio disparado por outra ferramenta, como Zapier, Make, n8n ou o seu próprio sistema.

> [!NOTE]
>
> O webhook envia uma mensagem por requisição, para um contato. Para enviar a
> mesma mensagem a uma lista, use as [campanhas](https://docs.blu.direct/campanhas/visao-geral.md).

## Gere a URL do webhook

1. Em **Números conectados**, clique em **Webhook** no card do número que vai enviar as mensagens.
2. Clique em **Gerar token**.
3. Copie a **URL do Webhook**. A janela também mostra um **Exemplo de uso (cURL)** pronto para copiar.

A URL tem este formato:

```
https://api.blu.direct/webhooks/SEU_TOKEN
```

> [!WARNING]
>
> Quem tiver a URL consegue enviar mensagens pelo seu número. Guarde-a como uma
> senha. Se ela vazar, clique em **Gerar novo token**: a URL anterior para de
> funcionar na hora, e você precisa atualizá-la nos sistemas que a usam.

## Envie uma mensagem de texto

Faça um `POST` para a URL com um corpo JSON contendo o telefone e o texto:

```bash theme={null}
curl -X POST "https://api.blu.direct/webhooks/SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "5511999999999", "message": "Oi, tudo bom?"}'
```

| Campo | Obrigatório | Descrição |
| - | - | - |
| `phone` | Sim | Telefone do contato com DDI e DDD, como `5511999999999`. Para celulares do Brasil, o blü confere com e sem o nono dígito e envia para a forma registrada no WhatsApp. |
| `message` | Sim\* | Texto da mensagem. Também aceito como `text`. |

\* Envie `message` ou `text`, ou use um template, como mostrado abaixo.

## Envie um template de campanha

Para enviar uma mensagem pronta, com imagens, áudio ou vídeo, use um [template de campanha](https://docs.blu.direct/campanhas/modelos.md) no lugar do texto.

1. Abra o template em **Templates de campanha** e clique em **Copiar link**. O link termina com o ID do template: `https://app.blu.direct/template/ID_DO_TEMPLATE`.
2. Envie o ID no campo `templateId`:

```bash theme={null}
curl -X POST "https://api.blu.direct/webhooks/SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone": "5511999999999", "templateId": "ID_DO_TEMPLATE", "nome": "Maria", "pedido": "1234"}'
```

### Personalize com variáveis

Os outros campos do corpo viram variáveis do template. No exemplo acima, um template com o texto `Olá, {{nome}}! Seu pedido {{pedido}} foi enviado.` chega como “Olá, Maria! Seu pedido 1234 foi enviado.”

* Escreva a variável no template entre chaves duplas, com o mesmo nome do campo: `{{nome}}`.
* Variáveis sem campo correspondente no corpo ficam vazias.
* Para variar o texto entre envios, use opções entre chaves simples separadas por `|`: `{Oi|Olá|Tudo bem}`. Cada envio escolhe uma delas.

> [!NOTE]
>
> Os botões do template não são enviados pelo webhook; o texto e os anexos, sim.

## Respostas

| Status | Quando acontece |
| - | - |
| `200` | A mensagem foi enviada para o WhatsApp: `{"success": true, "message": "Message sent"}`. |
| `400` | Falta o `phone` ou o texto da mensagem. O campo `error` explica o motivo. |
| `404` | O número de destino não tem WhatsApp, o token não existe mais, o número foi excluído ou o `templateId` não é um template da sua empresa. O campo `error` diz qual. |
| `503` | O número está desconectado do WhatsApp. Reconecte-o em **Números conectados** e tente de novo. |
| `500` | Erro inesperado. Tente de novo em alguns instantes. |

Uma resposta `200` confirma que o blü entregou a mensagem ao WhatsApp, não que ela chegou ao celular do contato. Confira o envio na conversa do contato em [Conversas](https://docs.blu.direct/atendimento/conversas.md).

## Boas práticas

* Envie apenas para contatos que autorizaram receber mensagens do seu número. Muitos envios para quem não conhece o número aumentam o risco de bloqueio.
* Espalhe envios em grande quantidade ao longo do tempo, em vez de disparar tudo de uma vez.
* Se o contato responder, a conversa segue normalmente no número: com o atendimento humano, o [agente de IA](https://docs.blu.direct/atendimento/agentes-ia.md) ou o [fluxo de respostas](https://docs.blu.direct/atendimento/fluxos.md) configurado nele.

Para o caminho inverso, em que o agente de IA avisa o seu sistema durante uma conversa, veja [webhooks do agente](https://docs.blu.direct/integracoes/webhooks-agente.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.