Enviar mensagens
POST /messages envia uma mensagem de WhatsApp a um número. É o que os conectores de Make, Zapier, n8n ou do seu CRM usam para avisar um cliente. A chave precisa da permissão messages:send.
Modelo ou texto livre
Modelo (type: template) |
Texto livre (type: text) |
|
|---|---|---|
| Para quem | Para qualquer número | Só se a pessoa escreveu para você nas últimas 24 h |
| O que você envia | templateId de um modelo aprovado e as variables dele |
text, até 4.096 caracteres |
| Contato | Se o número não for de nenhum contato, ele é criado (com contactName) |
A conversa precisa existir |
| Onde aparece | Na ficha do contato | Na conversa dela na caixa de entrada, como mais uma mensagem da equipe |
| Custo | Cobrado do saldo, como um envio pelo painel | Igual a uma resposta pela caixa de entrada |
Fora das 24 h o texto livre responde 409 OUTSIDE_SERVICE_WINDOW: envie um modelo. Para quem retirou o consentimento nada é enviado (400 CONTACT_OPTED_OUT).
Enviar um modelo
curl -X POST https://micuenta.whatsmarketing.es/api/v1/messages \
-H "Authorization: Bearer $WM_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-48213-aviso" \
-d '{
"to": "+34600111222",
"type": "template",
"templateId": "6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
"variables": { "1": "Ana" },
"contactName": "Ana García"
}'Os templateId vêm de GET /whatsapp/templates (permissão templates:read). As variáveis vão por número: {"1": "Ana"} preenche {{1}}. Se você tem várias linhas, phoneNumberId escolhe por qual sai; se faltar, a primeira conectada.
A resposta traz o id da mensagem e o status:
{ "id": "tpl_6f1c2b9e-…", "type": "template", "to": "+34600111222", "status": "PENDING", "error": null }Consultar o status
GET /messages/{id} devolve PENDING, SENT, DELIVERED, READ ou FAILED (com o motivo em error). Sem pressa: o status muda em segundos ou minutos, não é preciso perguntar mais de uma vez por minuto.
Repetir sem duplicar
Envie sempre Idempotency-Key com um valor que identifique o envio no seu sistema (o pedido, a consulta, o aviso). Se repetir a requisição com a mesma chave em 24 h, você recebe a mesma resposta e a mensagem não sai duas vezes.
Isso importa com 502 SEND_UNCERTAIN: significa que não sabemos se a mensagem saiu. Repita só com a mesma Idempotency-Key; sem ela, você poderia enviá-la duas vezes.
Limites
| Limite | Valor | Ao ultrapassar |
|---|---|---|
| Envios por chave e dia (UTC) | 1.000 | 429 DAILY_LIMIT_REACHED |
| Envios para o mesmo número e dia (UTC) | 20 | 429 RECIPIENT_DAILY_LIMIT_REACHED |
POST /messages |
60 por minuto e chave | 429 API_KEY_RATE_LIMITED |
GET /messages/{id} |
120 por minuto e chave | 429 API_KEY_RATE_LIMITED |
Para falar com milhares de pessoas de uma vez use uma campanha (POST /campaigns): ela divide o envio em lotes e mostra o custo antes. Se precisar de mais envios avulsos por dia, escreva para nós.
Erros
Todos os códigos, com a explicação, estão na referência de Mensagens.