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

# Números do WhatsApp

> Entendendo como os números de telefone do WhatsApp funcionam no Muchaw DEV.

Um **Número** no Muchaw DEV representa um número de telefone do WhatsApp conectado à sua conta. Cada número está associado a uma WhatsApp Business Account (WABA) e registrado na API Cloud da Meta.

## Ciclo de vida

```
PENDING → ACTIVE → DISCONNECTED
                 ↘ BANNED
```

| Status         | Descrição                                                                                |
| -------------- | ---------------------------------------------------------------------------------------- |
| `PENDING`      | O número foi enviado via Embedded Signup, mas o provisionamento ainda está em andamento. |
| `ACTIVE`       | O número está totalmente registrado e pronto para enviar/receber mensagens.              |
| `FAILED`       | O provisionamento falhou. Entre em contato com o suporte.                                |
| `DISCONNECTED` | O número foi desconectado (manualmente ou pelo dono do número).                          |
| `BANNED`       | O número foi banido pela Meta por violações de política.                                 |

## Fluxo de provisionamento

Quando um usuário final completa o fluxo de Embedded Signup ou Link de Cadastro, o Muchaw DEV automaticamente:

1. Troca o token temporário por um token de longa duração
2. Inscreve a WABA no App da Meta do Muchaw DEV (para receber webhooks)
3. Registra o número na API Cloud do WhatsApp
4. Configura o PIN de 2FA
5. Obtém o nome de exibição e a avaliação de qualidade da Meta
6. Atualiza o status do número para `ACTIVE`
7. Dispara um evento de webhook `number.activated` para os seus webhooks configurados

## Avaliação de Qualidade

A Meta atribui uma avaliação de qualidade a cada número de telefone com base no feedback dos usuários. Valores possíveis: `GREEN`, `YELLOW`, `RED`. Uma avaliação `RED` pode resultar em restrições ao envio de mensagens.

## Endpoints

| Método   | Caminho            | Descrição                                      |
| -------- | ------------------ | ---------------------------------------------- |
| `GET`    | `/api/numbers`     | Listar todos os números (filtrável por status) |
| `GET`    | `/api/numbers/:id` | Obter um número específico                     |
| `DELETE` | `/api/numbers/:id` | Desconectar um número                          |

## Listando números

```bash
# Listar todos os números ativos
curl "https://dev.muchau.com.br/api/numbers?status=ACTIVE" \
  -H "Authorization: Bearer $MUCHAW_API_KEY"
```

**Resposta:**

```json
{
  "data": [
    {
      "id": "clxyz123...",
      "wabaId": "123456789012345",
      "phoneNumberId": "987654321098765",
      "displayNumber": "+55 11 99999-0000",
      "qualityRating": "GREEN",
      "status": "ACTIVE",
      "tokenExpiresAt": null,
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:05:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}
```

## Schema completo de Número

```typescript
type WhatsAppNumber = {
  id: string;              // ID interno do Muchaw DEV (CUID)
  wabaId: string | null;   // ID da WhatsApp Business Account da Meta
  phoneNumberId: string | null; // ID do Número de Telefone da Meta (usado em chamadas de API)
  displayNumber: string;   // Número legível (ex: "+55 11 99999-0000")
  qualityRating: "GREEN" | "YELLOW" | "RED" | null;
  status: "PENDING" | "ACTIVE" | "FAILED" | "DISCONNECTED" | "BANNED";
  tokenExpiresAt: string | null; // ISO 8601 — se não nulo, o token precisa ser renovado
  createdAt: string;       // ISO 8601
  updatedAt: string;       // ISO 8601
};
```

## Desconectando um número

`DELETE /api/numbers/:id` remove o número da conta do desenvolvedor e revoga o acesso.
A conta do WhatsApp do usuário final em si NÃO é afetada — ele pode reconectar mais tarde via um novo fluxo de cadastro.

## Paginação

O endpoint de listagem suporta os parâmetros de query `limit` (1–100, padrão 20) e `offset` (padrão 0).