Concepts

WhatsApp Numbers

A Number in Muchaw DEV represents a WhatsApp phone number connected to your account. Each number is associated with a WhatsApp Business Account (WABA) and registered with Meta’s Cloud API.

Lifecycle

PENDING → ACTIVE → DISCONNECTED
                 ↘ BANNED
StatusDescription
PENDINGNumber has been submitted via Embedded Signup but provisioning is still in progress.
ACTIVENumber is fully registered and ready to send/receive messages.
FAILEDProvisioning failed. Contact support.
DISCONNECTEDNumber was disconnected (manually or by the number owner).
BANNEDNumber was banned by Meta due to policy violations.

Provisioning flow

When an end-user completes the Embedded Signup or Signup Link flow, Muchaw DEV automatically:

  1. Exchanges the temporary token for a long-lived token
  2. Subscribes the WABA to Muchaw DEV’s Meta App (to receive webhooks)
  3. Registers the number with WhatsApp Cloud API
  4. Configures 2FA PIN
  5. Fetches the display name and quality rating from Meta
  6. Updates the number status to ACTIVE
  7. Fires a number.activated webhook event to your configured webhooks

Quality Rating

Meta assigns a quality rating to each phone number based on user feedback. Possible values: GREEN, YELLOW, RED. A RED rating may result in message sending restrictions.

Endpoints

MethodPathDescription
GET/api/numbersList all numbers (filterable by status)
GET/api/numbers/:idGet a specific number
DELETE/api/numbers/:idDisconnect a number

Listing numbers

$# List all active numbers
$curl "https://dev.muchau.com.br/api/numbers?status=ACTIVE" \
>  -H "Authorization: Bearer $MUCHAW_API_KEY"

Response:

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}