# Enviar mensagens

Fonte: https://apiwpp.com/docs/guias/enviar-mensagens
Seção: Guias
Atualizado em: 2026-09-29

Texto, mídia, localização e templates pela fila de cada número, com reações, verificação de contatos e os eventos que contam o que houve com cada envio.

`POST /connections/{id}/send` não envia na hora: ele **coloca a mensagem na fila** do número e responde `202` com o job. A fila envia no ritmo que protege o número de bloqueios (veja [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio)), e o resultado chega pelos webhooks. A chave precisa do escopo `messages:send`.

**cURL**

```bash
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511988887777", "message": "Olá! Sua consulta está confirmada.", "clientRef": "pedido-1234"}'
```

**Node.js**

```js
const response = await fetch(`https://api.apiwpp.com/connections/${process.env.CONNECTION_ID}/send`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '5511988887777',
    message: 'Olá! Sua consulta está confirmada.',
    clientRef: 'pedido-1234',
  }),
});

if (response.status !== 202 && response.status !== 200) {
  throw new Error(`Envio recusado: ${response.status} ${await response.text()}`);
}
const { jobId, scheduledAt, position } = await response.json();
```

Resposta `202`

```json
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }
```

`jobId` identifica o envio na fila, `scheduledAt` é quando ele está previsto (unix em milissegundos) e `position` é o lugar dele na fila do número. Repetir a requisição com o mesmo `clientRef` na mesma conexão não enfileira de novo: a resposta é `200` com o job original e `"duplicate": true` (veja [Idempotência](https://apiwpp.com/docs/guias/idempotencia)). Mande sempre um `clientRef`: ele também volta nos eventos da mensagem.

A conexão precisa estar `open`. Em outro status, a resposta é `400` com `{ "error": "Connection not ready (status: close)" }`.

## O destinatário

`to` é o número com o código do país na frente, como `5511988887777`: só os dígitos são lidos. Antes de enviar, a apiwpp pergunta ao WhatsApp em qual endereço (JID) aquele número está registrado e envia para ele. Assim, contas antigas registradas sem o nono dígito recebem a mensagem mesmo quando você manda o número com ele; a apiwpp nunca inclui nem remove o nono dígito por conta própria.

`to` também aceita um JID, usado como veio:

| Formato | Destinatário |
| --- | --- |
| `5511988887777@s.whatsapp.net` | Uma pessoa, pelo telefone |
| `…@lid` | Uma pessoa identificada só pelo LID (o `jid` de um evento, veja [LID e contact.resolved](https://apiwpp.com/docs/guias/lid-e-contact-resolved)) |
| `…@g.us` | Um grupo em que o número está (veja [Listar grupos](https://apiwpp.com/docs/api/conexoes/listar-grupos)) |
| `…@broadcast`, `…@newsletter` | Uma lista de transmissão ou um canal |

Qualquer outra coisa é recusada na hora com `400` e `error: "invalid_recipient"`. Um número que **não está no WhatsApp** é aceito na fila, mas falha no envio, sem novas tentativas: com `clientRef`, chega um `message.send_failed` com `reason: not_on_whatsapp`. Para conferir antes, veja [Verificar números e perfis](#verificar-numeros-e-perfis).

## Tipos de mensagem

O conteúdo vai em `message`, `media`, `location` ou `template`. Sem nenhum deles, a resposta é `400` com `{ "error": "message, media, location, or template is required" }`. Se vier mais de um, `location` vale sozinho; com `media`, o texto de `message` vira a legenda quando `media.caption` não vem.

Antes de cada envio, o contato vê "digitando…" por `typingDelay` milissegundos (padrão: 1500).

### Texto

**Texto com 3 s de digitando…**

```json
{ "to": "5511988887777", "message": "Seu pedido saiu para entrega.", "typingDelay": 3000, "clientRef": "pedido-1234-saiu" }
```

### Mídia

A apiwpp baixa o arquivo de `media.url` na hora do envio e o manda ao WhatsApp. A URL tem de ser **https pública**: sem credenciais na URL, sem endereços privados ou internos, em cada redirecionamento também (até 3). O arquivo pode ter até 50 MB e o download, até 30 segundos. Uma URL recusada ou fora do ar faz a tentativa falhar; esgotadas as tentativas, chega `message.send_failed` com `reason: attempts_exhausted`.

| Campo | Obrigatório | Descrição |
| --- | --- | --- |
| `type` | sim | `image`, `video`, `audio`, `document` ou `sticker` |
| `url` | sim | URL https pública do arquivo |
| `caption` | não | Legenda (imagem, vídeo e documento) |
| `fileName` | não | Nome do arquivo que o contato vê (documento; padrão `document`) |
| `mimetype` | só em `document` | Tipo do arquivo, como `application/pdf`; sem ele, a resposta é `400` |
| `ptt` | não | Em `audio`, `true` envia como mensagem de voz |
| `gifPlayback` | não | Em `video`, `true` reproduz como GIF |

**Documento**

```json
{
  "to": "5511988887777",
  "media": {
    "type": "document",
    "url": "https://cdn.example.com/boletos/1234.pdf",
    "mimetype": "application/pdf",
    "fileName": "boleto-1234.pdf",
    "caption": "Segue o seu boleto."
  },
  "clientRef": "boleto-1234"
}
```

**Mensagem de voz**

```json
{ "to": "5511988887777", "media": { "type": "audio", "url": "https://cdn.example.com/audios/lembrete.ogg", "ptt": true } }
```

### Localização

`latitude` e `longitude` são obrigatórias (números); `name` e `address` são opcionais.

**Localização**

```json
{ "to": "5511988887777", "location": { "latitude": -23.5614, "longitude": -46.6559, "name": "Loja Paulista", "address": "Av. Paulista, 1000" } }
```

### Template

Um template é um texto salvo na conexão, com variáveis no formato `{{nome}}` (letras, números e `_`, sem começar por número), e pode ter uma mídia. Crie uma vez com [`POST /connections/{id}/templates`](https://apiwpp.com/docs/api/templates/criar-template) (escopo `templates:write`). O nome aceita letras, números, `_` e `-`, é guardado em minúsculas e é único na conexão (`409` se já existir):

**Criar o template**

```bash
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/templates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "confirmacao_consulta", "body": "Olá {{nome}}, até amanhã às {{hora}}."}'
```

Depois, envie pelo nome em `template`, com os valores em `variables`. As variáveis também valem na legenda da mídia do template, e a mídia do template substitui a da requisição:

**Enviar o template**

```json
{ "to": "5511988887777", "template": "confirmacao_consulta", "variables": { "nome": "Maria", "hora": "10h" }, "clientRef": "consulta-981" }
```

Um template que não existe responde `404`. Faltando alguma variável, a resposta é `400` com a lista:

Resposta `400`

```json
{ "error": "Missing required variables", "missingVariables": ["hora"] }
```

## Verificar números e perfis

[`POST /connections/{id}/contacts/check`](https://apiwpp.com/docs/api/contatos/verificar-numeros) pergunta ao WhatsApp se até 100 números estão registrados, com uma resposta por número, na mesma ordem. Com mais de 100, a resposta é `400`.

**Verificar números**

```bash
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/contacts/check \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["5511988887777", "5511955550000"]}'
```

Resposta `200`

```json
{
  "results": [
    { "phone": "5511988887777", "exists": true, "jid": "5511988887777@s.whatsapp.net" },
    { "phone": "5511955550000", "exists": false }
  ]
}
```

[`GET /connections/{id}/profile/{phone}`](https://apiwpp.com/docs/api/contatos/perfil-do-contato) traz o que o WhatsApp mostra do contato: `status` (o recado) e `pictureUrl`. Um campo escondido pelas configurações de privacidade dele não vem na resposta, e `name` hoje nunca é preenchido. As duas consultas exigem `messages:send`, porque perguntam ao WhatsApp a partir do número, como um envio, e a conexão precisa estar `open`.

## Reações

[`POST /connections/{id}/react`](https://apiwpp.com/docs/api/mensagens/reagir) reage a uma mensagem pelo `messageId` dela (num `message.incoming`, o id está em `data.raw.key.id`); `to` é a conversa. Ao contrário do envio, a reação não pergunta ao WhatsApp em qual endereço um telefone está registrado: `to` é usado como veio, e só dígitos viram `<dígitos>@s.whatsapp.net`. Para uma conta registrada sem o nono dígito ou uma conversa com LID, isso reage no endereço errado e a resposta ainda é `200`; por isso passe como `to` o `data.jid` do evento. Um `emoji` vazio remove a reação. Ao contrário do envio, a reação não passa pela fila: a resposta `200` com `{ "success": true }` quer dizer que ela foi enviada.

**Reagir**

```json
{ "messageId": "3EB0C767D26A1D8A3F52", "to": "5511988887777@s.whatsapp.net", "emoji": "👍" }
```

Editar e apagar mensagens enviadas, marcar mensagens como lidas e mostrar "digitando…" sem enviar são operações do plano PRO: veja [Operações de mensagem](https://apiwpp.com/docs/guias/operacoes-de-mensagem).

## A fila

Cada conexão tem a sua fila. Os envios saem um de cada vez, no ritmo do número: um intervalo de alguns segundos entre um envio e outro, um intervalo maior para o mesmo destinatário e os limites por minuto, hora e dia (mais baixos nos primeiros 14 dias do número). Uma tentativa que falha é repetida com espera crescente, até 3 tentativas no total.

- [`GET /connections/{id}/queue`](https://apiwpp.com/docs/api/mensagens/fila-do-numero) (escopo `connections:read`) mostra quantos envios aguardam (`pending`, `scheduled`), os limites atuais do número (`limits`), quanto deles já foi usado (`usage`) e o aquecimento (`warmup`).
- [`DELETE /connections/{id}/queue/{jobId}`](https://apiwpp.com/docs/api/mensagens/cancelar-mensagem-na-fila) (escopo `messages:send`) cancela um envio que ainda não saiu e responde `{ "cancelled": true }`; um job que já saiu ou não existe responde `404`.

**Consultar a fila**

```bash
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/queue \
  -H "Authorization: Bearer $API_KEY"
```

Resposta `200`

```json
{
  "pending": 1,
  "scheduled": 2,
  "limits": { "perMinute": 3, "perHour": 60, "perDay": 200, "newRecipientsPerDay": 100 },
  "usage": { "minute": 1, "hour": 12, "day": 40, "newRecipients": 7 },
  "warmup": { "createdAt": 1789646400000, "messagesSent": 40, "isInWarmup": false, "endsAt": 1790856000000 }
}
```

## Quando o envio é recusado

Estas respostas vêm na hora, e nada entra na fila:

| Status | Quando | O que fazer |
| --- | --- | --- |
| `400` | Corpo inválido, `invalid_recipient`, conexão fora de `open`, variáveis faltando (`missingVariables`) | Corrija a requisição ou espere a conexão abrir; repetir igual não resolve |
| `402` | `code: subscription_inactive`: o período de teste acabou ou uma fatura venceu e passou da carência | Regularize a assinatura no painel |
| `404` | Conexão ou template inexistente (ou de outra organização) | Confira os ids e o nome |
| `429` | Só num plano com limite de mensagens (o LITE e o PRO não têm): a cota da organização acabou (cabeçalho `X-Usage-Percent`) | Espere o próximo dia ou mês, ou mude de plano |
| `429` | `error: new_recipient_cap_reached`: o número já falou com o máximo de destinatários novos das últimas 24 horas | Espere os segundos de `Retry-After` |
| `503` | A instância que roda a conexão está mudando | Repita depois de `Retry-After`, com o mesmo `clientRef` |

Num plano com limite de mensagens, a cota conta junto as mensagens enviadas e as que estão na fila de todos os projetos da organização, e, perto do limite, a resposta de um envio aceito traz o cabeçalho `X-Usage-Warning`. Os detalhes de cada limite estão em [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio), e os de cada erro, em [Erros](https://apiwpp.com/docs/guias/erros).

## O que acontece depois

Cada envio é contado pelos webhooks do projeto:

| Evento | Quando |
| --- | --- |
| [`message.outgoing`](https://apiwpp.com/docs/webhooks/message-outgoing) | A mensagem saiu (`origin: API`, com o seu `clientRef` e o `messageId` do WhatsApp). Opcional: só para projetos com `emitOutgoing: true`, que também recebem o que é digitado no celular (`origin: PHONE`) |
| [`message.delivery`](https://apiwpp.com/docs/webhooks/message-delivery) | O status mudou: `sent`, `delivered`, `read` ou `failed`, com o `messageId` e o `clientRef` |
| [`message.send_failed`](https://apiwpp.com/docs/webhooks/message-send-failed) | Um envio **com `clientRef`** não vai acontecer: `attempts_exhausted`, `lease_expired`, `not_on_whatsapp` ou `reachout_timelocked` (a conta está num bloqueio temporário de novas conversas) |

A resposta `202` não traz o `messageId` do WhatsApp: ele chega nesses eventos. Guarde o `clientRef` junto do seu registro para ligar um ao outro.

## Próximos passos

- [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura): receba os eventos acima e verifique a assinatura.
- [Idempotência](https://apiwpp.com/docs/guias/idempotencia): repita envios sem duplicar mensagens.
- [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio): o ritmo da fila, o aquecimento e os destinatários novos.
- [Enviar mensagem](https://apiwpp.com/docs/api/mensagens/enviar-mensagem): a referência completa, com exemplos em cURL, Node.js, PHP e Python.
