Envio de mensagens
Enviar texto, mídia e resposta citada por um número, e ler as mensagens.
Os envios saem por um número pareado (veja Números e QR). Use a chave daquele número ou uma chave de API com o escopo Números que inclua o número.
Texto
curl -X POST "$API_URL/api/v1/instances/<id>/send" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "5511999990000", "body": "Olá! Seu pedido saiu para entrega."}'O to aceita +55..., 55... ou o JID do WhatsApp (...@s.whatsapp.net). A API normaliza o número, então a mesma pessoa não vira duas conversas. A resposta 200 traz o id da mensagem.
Mídia
Envie um arquivo (multipart) ou um endereço público com file_url. O type é image, video, audio ou document:
curl -X POST "$API_URL/api/v1/instances/<id>/send-media" \
-H "Authorization: Bearer $API_KEY" \
-F "to=5511999990000" \
-F "type=image" \
-F "caption=Cardápio da semana" \
-F "file_url=https://exemplo.com.br/cardapio.jpg"Resposta citada
curl -X POST "$API_URL/api/v1/instances/<id>/send-reply" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "5511999990000", "body": "Pode sim!", "quoted_message_id": "3EB0C0FFEE1234567890", "quoted_sender": "5511999990000@s.whatsapp.net"}'Ler as mensagens
curl -H "Authorization: Bearer $API_KEY" \
"$API_URL/api/v1/instances/<id>/messages?direction=inbound"Nas mensagens enviadas, status avança de sent para delivered e read, com delivered_at e read_at quando o aparelho confirma.
Erros comuns no envio
| Resposta | Motivo |
|---|---|
400 RECIPIENT_NOT_ON_WHATSAPP | O número de destino não tem WhatsApp. Não adianta repetir nem trocar de remetente. |
403 plan_limit | O plano chegou ao limite de mensagens do mês. |
403 ACCOUNT_SUSPENDED | A conta está suspensa por cobrança. |
429 | Envio rápido demais (espere o Retry-After antes de tentar de novo), ou o número está pausado (instance is paused: retome com PUT /pause) ou travado depois de um erro de reachout. |
502 | Erro do servidor do WhatsApp. Tente de novo em instantes. |
503 instance not ready | O número não está conectado. |
Envios em fila (clusters)
Um cluster reúne vários números e escolhe quem envia. POST /api/v1/clusters/<id>/send responde 202 com um job_id, e a fila tenta de novo sozinha. Acompanhe o job em GET /api/v1/clusters/<id>/queue/<job_id>, com a chave do cluster. Uma chave de API com o escopo Números envia e lê as mensagens do cluster quando todos os números dele estão na chave, mas não abre a fila.