Enviar mensagens

Envie texto, mídia ou template WABA com POST /v1/messages/send — a conversa é criada automaticamente se não existir. Requer escopo messages:send.

Escolha a conexão

Se a sua conta tem mais de uma conexão WhatsApp, informe whatsappId (ou whatsappName). Sem nenhum dos dois, a API escolhe automaticamente a primeira conexão whatsapp/waba conectada, por ordem crescente de id — o campo isDefault (que aparece em GET /v1/connections) não entra nessa escolha. Liste as conexões em GET /v1/connections e anote o id da que você quer usar; não deixe pro automático se a sua conta tem mais de uma conexão ativa. Sem nenhuma conexão whatsapp/waba cadastrada, a resposta é 404 ERR_NO_CONNECTION_AVAILABLE.

Envie um texto

curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/messages/send \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "number": "5534999990000", "whatsappId": 2, "body": "Olá! Seu pedido foi confirmado." }'

A resposta traz ticketId (a conversa) e messages[0].id.

Envie mídia (multipart)

Mídia vai por multipart/form-data, não JSON. O campo medias aceita imagem, áudio ou documento; body vira a legenda.

curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/messages/send \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -F "number=5534999990000" \
  -F "body=Segue o boleto" \
  -F "[email protected]"

import { readFileSync } from "node:fs";

const form = new FormData();
form.append("number", "5534999990000");
form.append("body", "Segue o boleto");
form.append("medias", new Blob([readFileSync("boleto.pdf")]), "boleto.pdf");

const r = await fetch("https://sua-instancia.whatix.cloud/wapi/v1/messages/send", {
  method: "POST",
  headers: { Authorization: "Bearer wtx_live_SEU_TOKEN" },
  body: form
});
console.log(await r.json());

Envie um template WABA

Fora da janela de 24h (veja abaixo), só templates aprovados são entregues. Envie templateData como objeto:

curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/messages/send \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5534999990000",
    "templateData": {
      "templateName": "confirmacao_pedido",
      "templateLanguage": "pt_BR",
      "templateParameters": ["Maria", "12345"]
    }
  }'

Por compatibilidade, templateData também aceita uma string JSON com o mesmo conteúdo ("{\"templateName\":...}"). Prefira o objeto: é mais legível e evita erro de escaping.

Acompanhe a entrega

Consulte GET /v1/messages/{messageId}/status com o id retornado no envio, use-o como messageId:

curl https://sua-instancia.whatix.cloud/wapi/v1/messages/ABC123/status \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN"

A resposta traz found: true e o ack numérico (0 a 5) com o status correspondente, aninhados em message:

{ "requestId": "...", "found": true, "message": { "id": "ABC123", "ack": 3, "status": "delivered" } }

status é um destes valores: queued, sent, server_ack, delivered, read, failed, received (mensagem recebida do contato, não enviada por você) ou unknown.

Janela de 24 horas

O WhatsApp só permite texto livre até 24h depois da última mensagem do cliente. Fora dessa janela:

Conexões WABA precisam de um template aprovado (templateData) — texto livre falha com erro da Meta.
Conexões Baileys (WhatsApp Web) não têm essa restrição, mas dependem do aparelho estar conectado.

Enviar body fora da janela numa conexão WABA não derruba a chamada com erro do Whatix — a mensagem é aceita pela API e rejeitada pela Meta. Consulte o status/ack pra confirmar a entrega real.

Envio sem registrar conversa

Por padrão (saveOnTicket omitido ou true), o envio cria/reaproveita uma conversa (ticketId). Com saveOnTicket: false, o envio é fire-and-forget: em conexões Baileys nenhuma conversa é criada (ticketId: null na resposta); em WABA um ticket efêmero ainda é criado internamente, mas não aparece na tela de atendimento.

curl -X POST https://sua-instancia.whatix.cloud/wapi/v1/messages/send \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "number": "5534999990000", "body": "Código de verificação: 482913", "saveOnTicket": false }'

Use isso para notificações transacionais (código de verificação, alerta) que não precisam virar atendimento.

Erros comuns

Código	HTTP	Causa
`ERR_MISSING_CONTENT`	400	Nenhum entre `body`, `medias` ou `templateData` foi enviado.
`ERR_NUMBER_INVALID`	400	`number` não tem dígitos válidos. Use E.164 sem `+` (ex.: `5534999990000`).
`ERR_CONNECTION_NOT_FOUND`	404	`whatsappId`/`whatsappName` não corresponde a uma conexão desta conta.
`ERR_NO_CONNECTION_AVAILABLE`	404	A conta não tem nenhuma conexão `whatsapp`/`waba` cadastrada.
`ERR_UNSUPPORTED_CHANNEL`	400	A conexão escolhida não é `whatsapp`/`waba` (só esses dois canais enviam pela API).

Veja o catálogo completo de erros.

Início

Guias

Referência

Enviar mensagens

Janela de 24 horas

Envio sem registrar conversa

Erros comuns

​Janela de 24 horas

​Envio sem registrar conversa

​Erros comuns

Janela de 24 horas

Envio sem registrar conversa

Erros comuns