Enviando mensagens

Há duas formas de chamar /instance/.../send/*:

Administrativa: POST /instance/{id}/send/{text,poll,buttons,pix}, com Authorization: Bearer (admin ou dono) — é o que o painel usa.
Self-service: POST /instance/send/{text,poll,buttons,pix}, sem :id, com o header token da própria instância.

O corpo é o mesmo nos dois casos; só muda autenticação e se o :id vai na URL.

Dry-run por padrão — leia isto antes de integrar

Toda chamada de envio é um preview, a não ser que você mande o campo confirm com o valor exato da string "ENVIAR" (maiúsculas, em português). Qualquer outra coisa — campo ausente, "confirm":"sim", "confirm":true — é tratado como dry-run: nenhuma mensagem é enviada de verdade, cota e rate limit não são verificados.

{ "to": "5583999999999", "text": "oi", "confirm": "ENVIAR" }

Isso é deliberado: dá para integrar e testar a chamada inteira (incluindo erro de allowlist, rate limit, formato) sem nunca arriscar mandar mensagem de verdade, até o dia em que você está pronto para ativar.

to é um número com DDI (só dígitos, sem + nem espaços) — é resolvido para JID do WhatsApp (IsOnWhatsApp) dentro do worker; você nunca monta o JID você mesmo.

Texto

curl -X POST -H "Authorization: Bearer <ADMIN_TOKEN>" -H "Content-Type: application/json" \
  -d '{"to":"5583999999999","text":"Olá!"}' \
  https://sua-instancia.exemplo/instance/{id}/send/text

Preview real (confirmado ao vivo, dry-run):

{
  "dryRun": true,
  "preview": "{\"conversation\":\"Olá!\"}",
  "note": "Texto puro — confiabilidade alta."
}

preview é uma string contendo o protojson da mensagem que seria enviada — não um objeto aninhado.

Enquete

{
  "to": "5583999999999",
  "question": "Gostou?",
  "options": ["Sim", "Não"],
  "selectableCount": 1
}

Formato nativo do protocolo de mensagens do WhatsApp — o mais confiável dos quatro tipos. Preview real confirmado:

{
  "dryRun": true,
  "preview": "{\"messageContextInfo\":{\"messageSecret\":\"...\"}, \"pollCreationMessage\":{\"name\":\"Gostou?\",\"options\":[{\"optionName\":\"Sim\"},{\"optionName\":\"Não\"}],\"selectableOptionsCount\":1}}",
  "note": "Formato nativo do protocolo, com suporte total do WhatsApp."
}

Botões (`quick_reply`)

{
  "to": "5583999999999",
  "body": "Escolha uma opção",
  "options": ["Sim", "Não"]
}

Até 3 botões. Não é um tipo de mensagem documentado oficialmente pelo WhatsApp — o backend monta manualmente o nó de protocolo necessário para renderizar os botões. Confirmado funcional em teste real (entrega + leitura), mas pode parar de funcionar sem aviso se o protocolo mudar.

Pix (`cta_copy`)

{
  "to": "5583999999999",
  "pixCode": "000201...",
  "displayText": "Pagar",
  "fallback": false
}

Mesmo mecanismo manual dos botões. fallback: true manda um texto simples em vez do botão interativo — útil se você perceber que o cliente de destino não está renderizando o botão. Confirmado funcional em teste real.

Mídia (imagem, vídeo, áudio, documento)

{
  "to": "5583999999999",
  "media": "<arquivo em base64>",
  "mimeType": "image/png",
  "caption": "Olá!"
}

media — conteúdo do arquivo em base64, até 16 MiB decodificados.
mimeType — obrigatório (ex.: image/png, video/mp4, audio/ogg, application/pdf). Por padrão o tipo de mídia (imagem/vídeo/áudio/documento) é inferido a partir dele.
mediaType — opcional, força o tipo (image, video, audio ou document) quando a inferência pelo mimeType não é o que você quer (ex.: mandar um PNG como documento em vez de imagem).
caption — opcional, texto que acompanha a mídia.
fileName — opcional, usado como nome do arquivo quando o tipo é document.

O que a documentação ainda não cobre

Taxas de entrega/latência sob carga com várias instâncias enviando ao mesmo tempo — não foi medido.