WS WSAPI

Mensagens

São duas rotas: POST /v1/message/send-text para texto e POST /v1/message/send-image para imagem com legenda. As duas usam a mesma autenticação (Authorization: Bearer + ?instanceId=) e o mesmo formato de telefone. Outros tipos (documento, 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.

Enviar imagem

A imagem pode vir como URL pública, base64 puro ou data URI. URL é mais leve — a engine baixa o arquivo. Base64 evita depender de hospedagem, útil quando a imagem é gerada na hora (um cupom fiscal recém-emitido, por exemplo).

terminal
curl -X POST "https://api.wsapi.app/v1/message/send-image?instanceId=$INSTANCE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5547999198263",
    "image": "https://exemplo.com/cupom.png",
    "caption": "Sua nota fiscal 🧾",
    "fileName": "cupom.png",
    "delayMessage": 2
  }'

# base64 também vale:
#   "image": "data:image/png;base64,iVBORw0KGgo..."

# 200 OK
{
  "success": true,
  "response": {
    "key": { "id": "3EB0...", "remoteJid": "5547999198263@s.whatsapp.net" },
    "message": { "imageMessage": { "caption": "Sua nota fiscal 🧾", "mimetype": "image/png" } },
    "status": "PENDING"
  }
}
  • image — obrigatório. URL pública, base64 puro ou data:image/png;base64,....
  • caption — opcional, legenda exibida abaixo da imagem.
  • fileName — opcional, nome do arquivo para quem recebe (default image.png).
  • delayMessage — igual ao texto: 0 a 30 segundos.

O mimetype é lido do data URI quando existe; sem ele, assume-se image/png. Como no texto, só metadados são registrados — a imagem e a legenda não são armazenadas.

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.