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

# Quickstart

> Envie sua primeira mensagem pelo WhatsApp em menos de 5 minutos.

## Pré-requisitos

* Uma conta no Muchaw DEV — [cadastre-se aqui](https://app.muchaw.dev/signup)
* Um número de WhatsApp conectado à sua conta (veja o Passo 2)

---

## Passo 1 — Obtenha sua chave de API

Após se cadastrar, acesse o [Dashboard](https://app.muchaw.dev) → **Chaves de API** → **Criar Chave**.

Copie a chave imediatamente — ela é exibida **apenas uma vez**. Armazene-a com segurança (por exemplo, no seu arquivo `.env`).

```bash
MUCHAW_API_KEY=mk_live_...
```

> **Warning**
>
> Nunca exponha sua chave de API em código client-side ou repositórios públicos.

---

## Passo 2 — Conecte um número de WhatsApp

A maneira mais fácil é criar um **Link de Cadastro** no Dashboard → **Links de Cadastro** → **Criar Link**.

Compartilhe o link com o dono do número. Eles completam um fluxo rápido de Embedded Signup do Facebook — seu número é registrado automaticamente.

Quando o número for ativado, você receberá um evento de webhook `number.activated` (se tiver um webhook configurado) e o status do número mudará para `ACTIVE`.

Você também pode recuperar o ID do número via API:

**`cURL`**

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

**`Node.js`**

```javascript Node.js
const res = await fetch("https://dev.muchau.com.br/api/numbers", {
  headers: { Authorization: `Bearer ${process.env.MUCHAW_API_KEY}` },
});
const { data } = await res.json();
console.log(data[0].id); // ex: "clxyz..."
```

**`Python`**

```python Python
import os, requests

resp = requests.get(
    "https://dev.muchau.com.br/api/numbers",
    headers={"Authorization": f"Bearer {os.environ['MUCHAW_API_KEY']}"},
)
numbers = resp.json()["data"]
print(numbers[0]["id"])
```

---

## Passo 3 — Envie uma mensagem

Use o ID do número do Passo 2 e o número de telefone do destinatário no formato internacional (ex: `5511999990000`).

**`cURL`**

```bash cURL
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á pelo Muchaw DEV!" }
  }'
```

**`Node.js`**

```javascript Node.js
const res = await fetch("https://dev.muchau.com.br/api/messages/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MUCHAW_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    number_id: "<SEU_NUMBER_ID>",
    to: "5511999990000",
    type: "text",
    text: { body: "Olá pelo Muchaw DEV!" },
  }),
});
const message = await res.json();
console.log(message.wa_message_id);
```

**`Python`**

```python Python
import os, requests

resp = requests.post(
    "https://dev.muchaw.com.br/api/messages/send",
    headers={
        "Authorization": f"Bearer {os.environ['MUCHAW_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "number_id": "<SEU_NUMBER_ID>",
        "to": "5511999990000",
        "type": "text",
        "text": {"body": "Olá pelo Muchaw DEV!"},
    },
)
print(resp.json()["wa_message_id"])
```

**Resposta:**

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

---

## Passo 4 — Receba mensagens (opcional)

Crie um webhook para receber eventos em tempo real quando mensagens chegarem:

**`cURL`**

```bash cURL
curl -X POST https://dev.muchau.com.br/api/webhooks \
  -H "Authorization: Bearer $MUCHAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-servidor.com/webhooks/whatsapp",
    "events": ["message.received", "message.delivered", "message.read"]
  }'
```

Salve o `secret` da resposta — você precisará dele para verificar assinaturas de webhook.

Veja [Receba Mensagens via Webhook](/docs/guides/receive-messages) para um guia completo de integração.

## Identificadores principais

* **number_id** — ID interno do Muchaw DEV para um número de telefone WhatsApp (formato CUID, ex: `clxyz123...`)
* **wa_message_id** — ID de mensagem da Meta (`wamid.HBg...`), retornado após um envio bem-sucedido
* **Números de telefone** — sempre no formato internacional sem `+` (ex: `5511999990000` para o Brasil)

## Fluxo de status para uma mensagem enviada

`sent` → `delivered` → `read` (ou `failed`)

Cada mudança de status dispara um evento de webhook se configurado.