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

# Enviando sua Primeira Mensagem

> Guia passo a passo para enviar uma mensagem do WhatsApp via API do Muchaw DEV.

## Pré-requisitos

* Uma conta no Muchaw DEV com uma chave de API
* Um número de WhatsApp com `status: ACTIVE` (veja o [Quickstart](/docs/quickstart))
* O número de telefone do destinatário deve ter o WhatsApp instalado

## Passo 1 — Encontre o ID do seu número

```bash
curl "https://dev.muchau.com.br/api/numbers?status=ACTIVE" \
  -H "Authorization: Bearer $MUCHAW_API_KEY"
```

Copie o `id` do número a partir do qual você quer enviar.

## Passo 2 — Envie uma mensagem de texto

```bash
curl -X POST https://dev.muchau.com.br/api/messages/send \
  -H "Authorization: Bearer $MUCHAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number_id": "<SEU_NUMBER_ID>",
    "to": "5511999990000",
    "type": "text",
    "text": { "body": "Olá! Seu pedido #1234 está pronto." }
  }'
```

**Resposta bem-sucedida:**

```json
{
  "id": "msg_01j...",
  "wa_message_id": "wamid.HBgL...",
  "status": "sent"
}
```

## Passo 3 — Evite envios duplicados (opcional)

Adicione o header `Idempotency-Key` para fazer retry seguro em requisições com falha:

```bash
curl -X POST https://dev.muchau.com.br/api/messages/send \
  -H "Authorization: Bearer $MUCHAW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234-notificacao-v1" \
  -d '{
    "number_id": "<SEU_NUMBER_ID>",
    "to": "5511999990000",
    "type": "text",
    "text": { "body": "Seu pedido #1234 está pronto." }
  }'
```

Se você chamar este endpoint novamente com o mesmo `Idempotency-Key` dentro de 24 horas, você receberá a resposta original sem enviar uma mensagem duplicada.

## Enviando diferentes tipos de mensagem

### Mensagem de template

Templates precisam ser pré-aprovados pela Meta. Use-os para a primeira mensagem a um usuário (fora de uma janela de conversa).

```json
{
  "number_id": "<SEU_NUMBER_ID>",
  "to": "5511999990000",
  "type": "template",
  "template": {
    "name": "confirmacao_pedido",
    "language": { "code": "pt_BR" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "1234" }
        ]
      }
    ]
  }
}
```

### Mensagem de imagem

```json
{
  "number_id": "<SEU_NUMBER_ID>",
  "to": "5511999990000",
  "type": "image",
  "image": {
    "link": "https://seu-cdn.com/recibo-1234.png",
    "caption": "Seu recibo"
  }
}
```

### Mensagem de documento

```json
{
  "number_id": "<SEU_NUMBER_ID>",
  "to": "5511999990000",
  "type": "document",
  "document": {
    "link": "https://seu-cdn.com/nota-fiscal-1234.pdf",
    "filename": "nota-fiscal-1234.pdf",
    "caption": "Nota Fiscal #1234"
  }
}
```

## Tratando erros

| Status HTTP | Código de erro     | Significado                                         |
| ----------- | ------------------ | --------------------------------------------------- |
| 401         | `UNAUTHORIZED`     | Chave de API inválida ou revogada                   |
| 403         | `FORBIDDEN`        | O número pertence a uma conta diferente             |
| 404         | `NOT_FOUND`        | ID do número não encontrado                         |
| 422         | `VALIDATION_ERROR` | Campos ausentes ou inválidos no corpo da requisição |

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Number not found",
    "status": 404
  }
}
```

## Acompanhe o status de entrega

Verifique o status da mensagem após o envio:

```bash
curl "https://dev.muchau.com.br/api/messages/<msg_id>" \
  -H "Authorization: Bearer $MUCHAW_API_KEY"
```

Ou configure um webhook para os eventos `message.delivered` e `message.read` para atualizações em tempo real.