> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.muchau.com.br/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.muchau.com.br/_mcp/server.

# Mensagens

> Enviando e recebendo mensagens do WhatsApp via API do Muchaw DEV.

## Visão geral

O módulo de Mensagens permite que você envie mensagens de qualquer um dos seus números de WhatsApp conectados e recupere o histórico de mensagens. Todas as mensagens são registradas e podem ser consultadas por direção, status, remetente ou destinatário.

## Tipos de mensagem

| Tipo          | Campo do payload | Descrição                                   |
| ------------- | ---------------- | ------------------------------------------- |
| `text`        | `text.body`      | Mensagem de texto simples                   |
| `template`    | `template`       | Template de mensagem aprovado pelo WhatsApp |
| `image`       | `image`          | Imagem (por Media ID ou URL)                |
| `document`    | `document`       | PDF, Word, etc.                             |
| `audio`       | `audio`          | Arquivo de áudio                            |
| `video`       | `video`          | Arquivo de vídeo                            |
| `location`    | `location`       | Coordenadas de latitude/longitude           |
| `interactive` | `interactive`    | Botões, listas, etc.                        |

## Enviando uma mensagem

`POST /api/messages/send`

O corpo da requisição deve incluir `number_id`, `to`, `type` e um campo correspondente ao `type`:

**`Texto`**

```json Texto
{
  "number_id": "clxyz123...",
  "to": "5511999990000",
  "type": "text",
  "text": {
    "body": "Olá! Como posso ajudar você hoje?"
  }
}
```

**`Template`**

```json Template
{
  "number_id": "clxyz123...",
  "to": "5511999990000",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "pt_BR" }
  }
}
```

**`Imagem`**

```json Imagem
{
  "number_id": "clxyz123...",
  "to": "5511999990000",
  "type": "image",
  "image": {
    "link": "https://exemplo.com/foto.jpg",
    "caption": "Confira isso!"
  }
}
```

**`Localização`**

```json Localização
{
  "number_id": "clxyz123...",
  "to": "5511999990000",
  "type": "location",
  "location": {
    "latitude": -23.5505,
    "longitude": -46.6333,
    "name": "São Paulo",
    "address": "Av. Paulista, 1000"
  }
}
```

## Idempotência

Adicione um header `Idempotency-Key` para evitar envios duplicados:

```http
POST /api/messages/send
Idempotency-Key: <string-única>
```

Se uma requisição com a mesma chave for recebida dentro de 24 horas, a resposta original é retornada sem enviar outra mensagem.

## Direções de mensagem

| Direção    | Descrição                               |
| ---------- | --------------------------------------- |
| `OUTBOUND` | Mensagens enviadas por você via API     |
| `INBOUND`  | Mensagens recebidas dos usuários finais |

## Status de mensagem

| Status      | Descrição                               |
| ----------- | --------------------------------------- |
| `sent`      | Aceita pelos servidores da Meta         |
| `delivered` | Entregue ao dispositivo do destinatário |
| `read`      | Lida pelo destinatário                  |
| `failed`    | Falha na entrega                        |

Atualizações de status são entregues via eventos de webhook.

## Consultando mensagens

```bash
# Listar mensagens recebidas para um número específico
curl "https://dev.muchau.com.br/api/messages?number_id=clxyz123...&direction=INBOUND&limit=50" \
  -H "Authorization: Bearer $MUCHAW_API_KEY"
```

## Schema completo de Mensagem

```typescript
type Message = {
  id: string;                    // ID interno de mensagem do Muchaw DEV
  numberId: string;              // O número de WhatsApp conectado que enviou/recebeu a mensagem
  waMessageId: string | null;    // wamid da Meta (ex: "wamid.HBgL...")
  direction: "INBOUND" | "OUTBOUND";
  fromNumber: string;            // Número do remetente (formato internacional)
  toNumber: string;              // Número do destinatário (formato internacional)
  type: "text" | "template" | "image" | "document" | "audio" | "video" | "location" | "interactive";
  body: unknown | null;          // Payload bruto da mensagem (estrutura específica por tipo)
  status: "sent" | "delivered" | "read" | "failed" | null;
  statusTimestamp: string | null; // ISO 8601 da última mudança de status
  createdAt: string;             // ISO 8601
};
```

## Parâmetros de query para listagem

* `number_id` (string, opcional) — filtrar por número
* `direction` (`INBOUND` | `OUTBOUND`, opcional)
* `status` (string, opcional)
* `to` (string, opcional) — filtrar por número do destinatário
* `from` (string, opcional) — filtrar por número do remetente
* `limit` (1–100, padrão 20)
* `offset` (padrão 0)

## Mídia

Para mensagens de mídia (imagem, documento, áudio, vídeo), você pode usar:

* `id` — um Media ID previamente enviado para os servidores da Meta
* `link` — uma URL HTTPS acessível publicamente para o arquivo de mídia

## Mensagens de template

Templates precisam ser pré-aprovados pela Meta. O campo `components` permite passar variáveis para os espaços reservados do template.