Números do WhatsApp

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:

Troca o token temporário por um token de longa duração
Inscreve a WABA no App da Meta do Muchaw DEV (para receber webhooks)
Registra o número na API Cloud do WhatsApp
Configura o PIN de 2FA
Obtém o nome de exibição e a avaliação de qualidade da Meta
Atualiza o status do número para ACTIVE
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

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

Resposta:

{
  "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
  }
}