UC-025 — Manage WhatsApp Business Numbers

Field	Value
ID	UC-025
Goal	Verify and manage available WhatsApp Business numbers
Channel	WhatsApp
Complexity	⭐ Basic
Estimated time	10 minutes
APIs involved	GET /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 main states of a WhatsApp Business number, as reported by Meta in status, 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://api.qlara.ai/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Number list

{
  "data": [
    {
      "id": 5,
      "messagingLimitTier": "TIER_10K",
      "phoneNumber": "+390212345678",
      "phoneQuality": "GREEN",
      "throughput": "STANDARD",
      "verifiedName": "ShopItalia S.r.l.",
      "messageSendingStatus": "AVAILABLE",
      "codeVerificationStatus": "VERIFIED",
      "status": "CONNECTED",
      "healthErrors": [],
      "healthInfo": [],
      "about": "Moda e accessori, spedizione in 24h",
      "address": "Via Torino 10, 20123 Milano",
      "description": "Il negozio online di ShopItalia",
      "email": "info@shopitalia.it",
      "profilePictureUrl": "https://fs-lora-namespace-public.fsn1.your-objectstorage.com/b394ab72/efd4987c/39b4879f6fed01f0d622453be1488c93?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=...",
      "vertical": "RETAIL",
      "websites": ["https://shopitalia.it"],
      "isOnBusinessApp": false,
      "createdAt": "2025-11-15 09:00:00.000+0000",
      "updatedAt": "2026-04-09 06:00:00.000+0000"
    },
    {
      "id": 6,
      "messagingLimitTier": "TIER_NOT_SET",
      "phoneNumber": "+390287654321",
      "phoneQuality": "UNKNOWN",
      "throughput": "STANDARD",
      "verifiedName": "SportZone by ShopItalia",
      "messageSendingStatus": "LIMITED",
      "codeVerificationStatus": "NOT_VERIFIED",
      "status": "PENDING",
      "healthErrors": [],
      "healthInfo": [],
      "about": null,
      "address": null,
      "description": null,
      "email": null,
      "profilePictureUrl": null,
      "vertical": null,
      "websites": [],
      "isOnBusinessApp": false,
      "createdAt": "2026-04-08 14:30:00.000+0000",
      "updatedAt": "2026-04-09 06:00:00.000+0000"
    }
  ],
  "page": 0,
  "limit": 10,
  "totalCount": 2,
  "totalPages": 1
}

The list is paginated, 10 numbers per page by default (limit and page query parameters), and leaves out DISCONNECTED numbers. Fields without a value are null. The id is the phoneNumberId to use when sending.

Behind the scenes — Quality rating and messaging limit

1. Quality rating: Meta assigns a quality score (phoneQuality) based on user feedback. Possible values are GREEN (good), YELLOW (warning), RED (critical) and UNKNOWN (not rated yet). A RED rating can lead to number suspension.
2. Messaging limit: The tier (messagingLimitTier) determines how many unique recipients you can message in 24 hours: TIER_50, TIER_250, TIER_1K (1,000), TIER_10K (10,000), TIER_100K (100,000), TIER_UNLIMITED; TIER_NOT_SET until Meta assigns one. 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 (codeVerificationStatus) and display name review.
4. Sending status: messageSendingStatus tells whether Meta lets the number send: AVAILABLE, LIMITED or BLOCKED. When there is a problem, healthErrors describes it, with the possible solution.
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://api.qlara.ai/api/message-server/whatsapp/phone-numbers/5 \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Number details

{
  "id": 5,
  "messagingLimitTier": "TIER_10K",
  "phoneNumber": "+390212345678",
  "phoneQuality": "GREEN",
  "throughput": "STANDARD",
  "verifiedName": "ShopItalia S.r.l.",
  "messageSendingStatus": "AVAILABLE",
  "codeVerificationStatus": "VERIFIED",
  "status": "CONNECTED",
  "healthErrors": [],
  "healthInfo": [],
  "about": "Moda e accessori, spedizione in 24h",
  "address": "Via Torino 10, 20123 Milano",
  "description": "Il negozio online di ShopItalia",
  "email": "info@shopitalia.it",
  "profilePictureUrl": "https://fs-lora-namespace-public.fsn1.your-objectstorage.com/b394ab72/efd4987c/39b4879f6fed01f0d622453be1488c93?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=...",
  "vertical": "RETAIL",
  "websites": ["https://shopitalia.it"],
  "isOnBusinessApp": false,
  "createdAt": "2025-11-15 09:00:00.000+0000",
  "updatedAt": "2026-04-09 06:00:00.000+0000"
}

The detail has the same fields as the list, and also answers for numbers that the list leaves out, such as DISCONNECTED ones.

Check quality rating and tier before campaigns

Before launching large campaigns, verify that the phoneQuality is GREEN and that the messagingLimitTier is sufficient for the expected volume. A TIER_1K tier cannot handle a campaign with 5,000 recipients.

Expected result

Step	Action	Result
1	GET /phone-numbers	Full list of numbers with status and tier
2	GET /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://api.qlara.ai/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.data[] | {id, verifiedName, status, phoneQuality, messagingLimitTier}'

# 2. Find connected numbers with sufficient tier for the campaign
echo "=== Numbers ready for campaign (CONNECTED + TIER >= 10K) ==="
curl -s -X GET https://api.qlara.ai/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY" | jq '[.data[] | select(.status == "CONNECTED" and (.messagingLimitTier == "TIER_10K" or .messagingLimitTier == "TIER_100K" or .messagingLimitTier == "TIER_UNLIMITED"))]'

# 3. Details of the chosen number
PHONE_ID=5
echo "=== Number details ${PHONE_ID} ==="
curl -s -X GET "https://api.qlara.ai/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 connected numbers client-side:

curl -s -X GET https://api.qlara.ai/api/message-server/whatsapp/phone-numbers \
  -H "X-Api-Key: YOUR_API_KEY" \
  | jq '[.data[] | select(.status == "CONNECTED")]'

Monitor onboarding status

For a number in PENDING status, perform periodic polling:

# Check every 30 seconds until the status changes
PHONE_ID=6
while true; do
  STATUS=$(curl -s -X GET "https://api.qlara.ai/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": "PHONE_NUMBER_NOT_FOUND"
}

Solution: Verify the number ID with a GET on the full list: it must be the numeric id of a number of your account. The ID may have changed after a reconfiguration.

401 Unauthorized — Missing or invalid API Key

The endpoint answers 401 with an empty body.

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

Next steps

• UC-003 — Send WhatsApp Template: Send a single WhatsApp message
• UC-022 — Bulk WhatsApp Campaign: Use the chosen number for a bulk campaign
• UC-013 — WhatsApp Template Workflow: Create templates for the selected number
• UC-024 — Templates with Tracked Links: Add tracking to templates

References

• API Reference — WhatsApp Phone Numbers: Full phone numbers endpoint documentation
• WhatsApp Guide: WhatsApp channel specifications and onboarding
• Authentication Guide: Details on API Key and Basic Auth