Ir para o conteúdo
WhatsMarketingDeveloper Hub

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
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:

JSON
{ "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.