Conceitos

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
StatusDescrição
PENDINGO número foi enviado via Embedded Signup, mas o provisionamento ainda está em andamento.
ACTIVEO número está totalmente registrado e pronto para enviar/receber mensagens.
FAILEDO provisionamento falhou. Entre em contato com o suporte.
DISCONNECTEDO número foi desconectado (manualmente ou pelo dono do número).
BANNEDO 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étodoCaminhoDescrição
GET/api/numbersListar todos os números (filtrável por status)
GET/api/numbers/:idObter um número específico
DELETE/api/numbers/:idDesconectar 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:

1{
2  "data": [
3    {
4      "id": "clxyz123...",
5      "wabaId": "123456789012345",
6      "phoneNumberId": "987654321098765",
7      "displayNumber": "+55 11 99999-0000",
8      "qualityRating": "GREEN",
9      "status": "ACTIVE",
10      "tokenExpiresAt": null,
11      "createdAt": "2024-01-15T10:00:00.000Z",
12      "updatedAt": "2024-01-15T10:05:00.000Z"
13    }
14  ],
15  "pagination": {
16    "total": 1,
17    "limit": 20,
18    "offset": 0
19  }
20}