# Enviar mensagem

Fonte: https://apiwpp.com/docs/api/mensagens/enviar-mensagem
Seção: Mensagens
Atualizado em: 2026-09-28

`POST /connections/{id}/send`

Coloca a mensagem (texto, mídia, localização ou template) na fila do número e responde `202` com a posição na fila e o horário previsto. O envio acontece em seguida, no ritmo que protege o número, e os webhooks `message.outgoing` e `message.delivery` contam o que aconteceu com ele. Escopo necessário: `messages:send`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |
| `Content-Type` | sim | `application/json` |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador da conexão (o número) que envia. |

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `to` | `string` | sim | Destinatário: um número de telefone com código do país e DDD (por exemplo, `5511988887777`; só os dígitos são lidos) ou um JID: uma pessoa (`…@s.whatsapp.net` ou `…@lid`), um grupo (`…@g.us`), uma lista de transmissão ou um canal. Para um número, o gateway pergunta ao WhatsApp em qual endereço ele está registrado e envia para esse endereço. |
| `message` | `string` | não | Texto da mensagem. |
| `typingDelay` | `number` | não | Por quantos milissegundos o indicador “digitando…” aparece antes do envio. Padrão: 1500. |
| `media` | `object` | não | Mídia a partir de uma URL https pública. |
| `media.type` | `string` | sim | Tipo da mídia. Valores: `"image"`, `"video"`, `"audio"`, `"document"`, `"sticker"`. |
| `media.url` | `string · uri` | sim | URL https pública do arquivo. Endereços privados e internos são recusados. (formato `^https://`) |
| `media.caption` | `string` | não | Legenda. |
| `media.fileName` | `string` | não | Nome do arquivo. |
| `media.mimetype` | `string` | não | Tipo MIME do arquivo (por exemplo, `application/pdf`). Obrigatório quando `type` é `document`. |
| `media.ptt` | `boolean` | não | Com `audio`, envia o áudio como mensagem de voz. |
| `media.gifPlayback` | `boolean` | não | Com `video`, reproduz o vídeo como GIF. |
| `location` | `object` | não | Uma localização. |
| `location.latitude` | `number` | sim | Latitude. |
| `location.longitude` | `number` | sim | Longitude. |
| `location.name` | `string` | não | Nome do local. |
| `location.address` | `string` | não | Endereço do local. |
| `template` | `string` | não | Nome de um template da conexão (criado com `POST /connections/{id}/templates`). O texto e a mídia do template substituem `message` e `media`. |
| `variables` | `object` | não | Valores das variáveis do template, por nome: `{"nome": "Maria", "hora": "10h"}`. (chaves livres, valores string) |
| `clientRef` | `string` | não | Seu identificador do envio (o id do pedido, da notificação). É a chave de idempotência: um `clientRef` fica reservado por 7 dias na conexão, e a repetição responde `200` com o job original. Volta como `clientRef` nos eventos `message.outgoing` (origem `API`) e `message.delivery` da mensagem. (até 200 caracteres) |

## Exemplo de requisição

### cURL

```bash
curl -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

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

### PHP

```php
$response = Http::withToken($apiKey)
    ->post("https://api.apiwpp.com/connections/{$connectionId}/send", [
        'to' => '5511988887777',
        'message' => 'Olá! Sua consulta está confirmada.',
        'clientRef' => 'pedido-1234',
    ]);
```

### Python

```python
import requests

response = requests.post(
    f"https://api.apiwpp.com/connections/{connection_id}/send",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "to": "5511988887777",
        "message": "Olá! Sua consulta está confirmada.",
        "clientRef": "pedido-1234",
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | Um envio anterior com o mesmo `clientRef`, na mesma conexão, já enfileirou esta mensagem: a resposta traz o job original com `"duplicate": true`, e nada é enfileirado de novo. `scheduledAt` e `position` vêm `null` enquanto o envio original ainda está entrando na fila. |
| 202 |  | A mensagem entrou na fila. Traz `jobId`, `scheduledAt` (quando o envio está previsto, unix em milissegundos) e `position` (o lugar na fila). Num plano com limite de mensagens, perto desse limite a resposta traz o cabeçalho `X-Usage-Warning` (`Approaching limit: …% used`). Cabeçalhos: `X-Usage-Warning`. |
| 400 | `invalid_recipient` | `to` não é um número de telefone nem o JID de uma pessoa, de um grupo, de uma lista de transmissão ou de um canal. O corpo traz `error` e `message`. |
| 400 |  | A conexão não está `open` (`Connection not ready (status: …)`), ou o corpo não traz `message`, `media`, `location` nem `template`, ou a mídia ou a localização estão incompletas (`media.url`; `media.mimetype` num `document`; `location.latitude` e `location.longitude`). |
| 400 |  | O template precisa de variáveis que não vieram em `variables`: o corpo é `{"error": "Missing required variables", "missingVariables": [...]}`, com a lista das que faltam. |
| 400 | `FST_ERR_VALIDATION` | O corpo não segue o schema da operação (por exemplo, sem `to`); `message` diz o que está errado. |
| 401 |  | Sem chave de API, ou com uma chave inválida (desconhecida, revogada ou expirada). |
| 402 | `subscription_inactive` | A organização dona da conexão não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Regularize o pagamento no painel e repita. |
| 403 |  | A chave de API não tem o escopo `messages:send`; a mensagem do erro cita o escopo que falta. |
| 404 |  | A conexão não existe ou não é de quem chama (o recurso de outra pessoa responde igual a um que não existe). Também quando o `template` não existe na conexão. |
| 429 | `new_recipient_cap_reached` | O número já alcançou o limite de destinatários novos das últimas 24 horas. O corpo traz `error` e `message`; espere os segundos de `Retry-After`. Cabeçalhos: `Retry-After`. |
| 429 |  | Só num plano com limite de mensagens (os planos LITE e PRO não têm): a cota diária ou mensal da organização acabou. O cabeçalho `X-Usage-Percent` traz o uso, e `error` diz qual limite foi; não há `Retry-After`, a cota volta no próximo dia ou mês. Cabeçalhos: `X-Usage-Percent`. |
| 429 |  | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de `Retry-After`. Cabeçalhos: `Retry-After`. |
| 503 |  | A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere Retry-After segundos e tente de novo. Cabeçalhos: `Retry-After`. |

### 202 Accepted

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

## Detalhes

A conexão precisa estar `open`. O envio precisa de conteúdo: `message`, `media`, `location` ou `template`; só `to` é obrigatório no schema.

Envie um `clientRef` para tornar a requisição idempotente e correlacionar os eventos: repetir com o mesmo valor na mesma conexão responde `200` com o job original e `"duplicate": true`, sem enfileirar nada. A repetição é reconhecida antes das outras verificações do envio (template, status da conexão, cota), então não vira erro enquanto o job original existe. Veja [Idempotência](https://apiwpp.com/docs/guias/idempotencia).

A resposta `202` traz o `jobId` da fila, não o id da mensagem no WhatsApp: o `messageId` chega nos eventos `message.outgoing` (com `origin: "API"`) e `message.delivery`, com o seu `clientRef`. Se o envio aceito não acontecer (o número de `to` não está no WhatsApp, as tentativas acabaram, o número está com as novas conversas bloqueadas), um envio com `clientRef` gera o evento `message.send_failed`.

A cota do plano é da organização: as mensagens enviadas e enfileiradas de todos os projetos dela contam juntas. Um destinatário que não trocou mensagem com o número nos últimos 28 dias desde a conexão atual é um destinatário novo; parear de novo, mesmo o mesmo número, torna todos os contatos novos. O número tem um limite de destinatários novos a cada 24 horas, menor enquanto ele está conectado há menos de 14 dias (`GET /connections/{id}/queue` mostra o limite e o uso). Veja [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio).

Guia: [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens).
