Skip to main content

UC-025 — Manage WhatsApp Business Numbers

FieldValue
IDUC-025
GoalVerify and manage available WhatsApp Business numbers
ChannelWhatsApp
Complexity⭐ Basic
Estimated time10 minutes
APIs involvedGET /api/message-server/whatsapp/phone-numbers, GET /api/message-server/whatsapp/phone-numbers/{phoneNumberId}

Real-world scenarios​

  • ShopItalia — Check available numbers: Before launching a campaign, the marketing team verifies which WhatsApp Business numbers are active and ready for sending.
  • MultiStore — Check onboarding status: The company has requested the activation of a new number for the "SportZone" brand and wants to check the onboarding status.
  • AgenziaViaggi — Choose number for campaign: With 3 active numbers (one per brand), the team selects the correct number to associate with the summer campaign.

Number management flow​

The diagram shows the three possible states of a WhatsApp Business number and the resulting actions: use for sending, wait for onboarding or contact support.

Prerequisites​

  • Active API Key with WhatsApp permissions
  • At least one WhatsApp Business number registered on the platform

Step 1 — Retrieve the list of available numbers​

Query the endpoint to get all WhatsApp Business numbers associated with your account.

curl -X GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Number list​

{
  "phoneNumbers": [
    {
      "phoneNumberId": "waba-num-001",
      "phoneNumber": "+390212345678",
      "displayName": "ShopItalia",
      "qualityRating": "GREEN",
      "status": "ACTIVE",
      "messagingLimit": "TIER_10K",
      "verifiedName": "ShopItalia S.r.l.",
      "platform": "CLOUD_API"
    },
    {
      "phoneNumberId": "waba-num-002",
      "phoneNumber": "+390287654321",
      "displayName": "SportZone",
      "qualityRating": "UNKNOWN",
      "status": "PENDING",
      "messagingLimit": "TIER_1K",
      "verifiedName": "SportZone by ShopItalia",
      "platform": "CLOUD_API"
    },
    {
      "phoneNumberId": "waba-num-003",
      "phoneNumber": "+390211223344",
      "displayName": "ShopItalia Support",
      "qualityRating": "GREEN",
      "status": "ACTIVE",
      "messagingLimit": "TIER_100K",
      "verifiedName": "ShopItalia S.r.l.",
      "platform": "CLOUD_API"
    }
  ],
  "total": 3
}
Behind the scenes — Quality rating and messaging limit
  1. Quality rating: Meta assigns a quality score based on user feedback. Possible values are GREEN (good), YELLOW (warning) and RED (critical). A RED rating can lead to number suspension.
  2. Messaging limit: The tier determines how many unique messages you can send in 24 hours: TIER_1K (1,000), TIER_10K (10,000), TIER_100K (100,000), UNLIMITED. The tier increases automatically with good quality rating.
  3. PENDING status: A number in PENDING status is completing the verification process with Meta. The process includes OTP verification and display name review.
  4. CLOUD_API platform: Indicates that the number uses Meta's Cloud API (managed by Meta). The alternative is ON_PREMISE for local installations of the Business API.
  5. Verified name: The Meta-verified name that appears in the recipient's WhatsApp chat header. It cannot be changed without a new verification request.

Step 2 — Check the details of a specific number​

To get detailed information about a single number, use the ID returned in the previous step.

curl -X GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers/waba-num-001 \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Number details​

{
  "phoneNumberId": "waba-num-001",
  "phoneNumber": "+390212345678",
  "displayName": "ShopItalia",
  "qualityRating": "GREEN",
  "status": "ACTIVE",
  "messagingLimit": "TIER_10K",
  "verifiedName": "ShopItalia S.r.l.",
  "platform": "CLOUD_API",
  "nameStatus": "APPROVED",
  "accountMode": "LIVE",
  "lastOnboardedAt": "2025-11-15T10:00:00+01:00",
  "wabaId": "waba-acct-shopitalia-001"
}

:::tip Check quality rating and tier before campaigns Before launching large campaigns, verify that the qualityRating is GREEN and that the messagingLimit is sufficient for the expected volume. A TIER_1K tier cannot handle a campaign with 5,000 recipients. :::

Expected result​

StepActionResult
1GET /phone-numbersFull list of numbers with status and tier
2GET /phone-numbers/{id}Full details of a specific number

Complete end-to-end example​

# 1. Retrieve all available numbers
echo "=== WhatsApp Business Numbers ==="
curl -s -X GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.phoneNumbers[] | {phoneNumberId, displayName, status, qualityRating, messagingLimit}'

# 2. Find active numbers with sufficient tier for the campaign
echo "=== Numbers ready for campaign (ACTIVE + TIER >= 10K) ==="
curl -s -X GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY" | jq '[.phoneNumbers[] | select(.status == "ACTIVE" and (.messagingLimit == "TIER_10K" or .messagingLimit == "TIER_100K" or .messagingLimit == "UNLIMITED"))]'

# 3. Details of the chosen number
PHONE_ID="waba-num-001"
echo "=== Number details ${PHONE_ID} ==="
curl -s -X GET "https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers/${PHONE_ID}" \
  -H "X-Api-Key: YOUR_API_KEY" | jq .

Variants​

Filter numbers by status​

To quickly find only active numbers client-side:

curl -s -X GET https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY" \
  | jq '[.phoneNumbers[] | select(.status == "ACTIVE")]'

Monitor onboarding status​

For a number in PENDING status, perform periodic polling:

# Check every 30 seconds until the status changes
PHONE_ID="waba-num-002"
while true; do
  STATUS=$(curl -s -X GET "https://lora-api.agiletelecom.com/api/message-server/whatsapp/phone-numbers/${PHONE_ID}" \
    -H "X-Api-Key: YOUR_API_KEY" | jq -r '.status')
  echo "$(date): Status = $STATUS"
  if [ "$STATUS" != "PENDING" ]; then
    echo "Onboarding completed with status: $STATUS"
    break
  fi
  sleep 30
done

Common errors​

404 Not Found — Number not found​

{
  "status": "fail",
  "data": {
    "phoneNumberId": "Phone number not found: waba-num-999"
  }
}

Solution: Verify the number ID with a GET on the full list. The ID may have changed after a reconfiguration.

401 Unauthorized — Missing or invalid API Key​

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Solution: Verify that the X-Api-Key header is present and that the key is active in the platform dashboard.

403 Forbidden — Insufficient permissions​

{
  "status": "fail",
  "data": {
    "authorization": "API key does not have permission to access WhatsApp phone numbers"
  }
}

Solution: Your API Key may not have WhatsApp channel permissions. Check the permissions in the platform dashboard or contact the administrator.

Next steps​

References​