> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whatix.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar mensagens

> Texto, mídia, template WABA, janela de 24h e como acompanhar a entrega.

Envie texto, mídia ou template WABA com [`POST /v1/messages/send`](/pt/referencia/mensagens/enviar-mensagem-para-um-número-cria-conversa-se-preciso) — a conversa é criada automaticamente se não existir. Requer escopo `messages:send`.

<Steps>
  <Step title="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`](/pt/referencia/conexões/listar-conexões-canais-da-conta) 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`.
  </Step>

  <Step title="Envie um texto">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash cURL theme={null}
      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 "medias=@boleto.pdf"
      ```

      ```js Node theme={null}
      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());
      ```
    </CodeGroup>
  </Step>

  <Step title="Envie um template WABA">
    Fora da janela de 24h (veja abaixo), só templates aprovados são entregues. Envie `templateData` como objeto:

    ```bash theme={null}
    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"]
        }
      }'
    ```

    <Note>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.</Note>
  </Step>

  <Step title="Acompanhe a entrega">
    Consulte [`GET /v1/messages/{messageId}/status`](/pt/referencia/mensagens/consultar-status-de-entrega-de-uma-mensagem) com o `id` retornado no envio, use-o como `messageId`:

    ```bash theme={null}
    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`:

    ```json theme={null}
    { "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`.
  </Step>
</Steps>

## 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.

<Warning>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.</Warning>

## 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.

```bash theme={null}
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](/pt/erros-e-limites).