Ir para o conteúdo

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

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

bash
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

bash
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

bash
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

RespostaMotivo
400 RECIPIENT_NOT_ON_WHATSAPPO número de destino não tem WhatsApp. Não adianta repetir nem trocar de remetente.
403 plan_limitO plano chegou ao limite de mensagens do mês.
403 ACCOUNT_SUSPENDEDA conta está suspensa por cobrança.
429Envio 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.
502Erro do servidor do WhatsApp. Tente de novo em instantes.
503 instance not readyO 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.