Mensagens

A rota principal é POST /v1/message/send-text. Ela aceita um body JSON com o número de destino e o conteúdo. Outros tipos (mídia, template, lista) entram nas próximas semanas.

Enviar texto

terminal

curl -X POST "https://api.wsapi.app/v1/message/send-text?instanceId=$INSTANCE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5547999198263",
    "message": "Olá, mundo! 👋",
    "delayMessage": 2
  }'

# 200 OK
{
  "id": "wamid.HBg...",
  "status": "queued",
  "timestamp": 1736001234
}

Campos do body

phone — string, formato 55DDDxxxxxxxx (Brasil). Sem +, sem espaços.
message — string, suporta emoji e quebra de linha (\n). Limite ~4096 caracteres.
delayMessage — opcional, inteiro de 0 a 30 (segundos). Atrasa o envio para humanizar disparos em sequência.

Códigos de retorno

200 OK — mensagem aceita e enfileirada para envio.
400 Bad Request — body inválido (ex.: telefone fora do padrão).
401 Unauthorized — token ausente ou expirado.
403 Forbidden — token não pertence a esta instância.
409 Conflict — instância não está conectada (state !== "open").
429 Too Many Requests — limite de fila atingido. Espere e tente de novo.

Boas práticas

Sempre faça GET /v1/instance/status antes do envio em massa.
Use delayMessage em loops de envio. Disparo super rápido aciona heurísticas anti-spam do WhatsApp.
Trate 409 como sinal para mostrar QR Code ao cliente.
Não envie para listas frias ou sem opt-in. É a forma mais rápida de queimar o número.

Limites

Não impomos limite de mensagens por minuto. O limite real é o do próprio WhatsApp — que é dinâmico e depende de quanto seu número é "novo", da quantidade de mensagens marcadas como spam, etc. Para produção crítica, recomendamos a Cloud API oficial.