WABA-level listing: This operation calls GET /{businessAccountId}/phone_numbers and returns all numbers registered under the supplied WABA ID. Fields returned per number: id, display_phone_number, verified_name, quality_rating, and code_verification_status.
When to Use
- Multi-number account audit: A compliance workflow runs monthly to enumerate all phone numbers under the business account and confirm each one has
code_verification_status of VERIFIED.
- Dynamic sender selection: A campaign orchestrator retrieves the full list of active numbers, then selects the one with the best quality rating (
GREEN) to route a batch of outbound messages.
- Provisioning inventory: An internal admin workflow builds a live inventory report of all registered sending numbers, their display values, and current quality tiers for business review.
- Bulk quality sweep: A daily monitoring workflow lists all numbers and splits any with
RED quality rating into a separate branch that triggers a remediation ticket per number.
- Number decommission check: Before deregistering a number, a workflow lists all registered numbers to confirm it appears in the WABA and is not already removed.
Configuration
Connection
| Field | Required | Description |
|---|
accessToken | Required | Permanent System User access token. Store in BizFirst Credentials Manager. |
phoneNumberId | Required | Any phone number ID in the WABA — used to authenticate the request. The listing is scoped to the WABA, not a single number. |
apiVersion | Optional | Meta Graph API version. Defaults to v18.0. |
Operation
| Field | Required | Description |
|---|
wabaId | Required | The WhatsApp Business Account ID (numeric string from Meta Business Manager). All phone numbers under this WABA are returned. |
Sample Configuration
{
"resource": "phone-number",
"operation": "list",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"wabaId": "987654321098765"
}
Validation Errors
| Error | Cause |
|---|
accessToken is required | The accessToken field is empty. |
wabaId is required | No WABA ID was provided in the operation fields. |
100 (Meta) | Invalid WABA ID — the account does not exist or the token has no access to it. |
200 (Meta) | Insufficient permissions — the access token lacks whatsapp_business_management. |
timeout | The Meta Graph API did not respond within the configured timeout. |
Output
Success Port
| Field | Type | Description |
|---|
phoneNumbers | array | Array of phone number objects. Each element contains id, displayPhoneNumber, verifiedName, qualityRating, and codeVerificationStatus. |
count | number | Total number of phone numbers returned. |
status | string | "success". |
rawResponse | string | Full raw JSON from the Meta Graph API including the data array. |
Error Port
| Field | Type | Description |
|---|
status | string | "failed" or "error". |
errorCode | string | Meta error code or "timeout". |
errorMessage | string | Human-readable error description. |
Sample Output
{
"phoneNumbers": [
{
"id": "123456789012345",
"displayPhoneNumber": "+1 415-555-2671",
"verifiedName": "Acme Corp Support",
"qualityRating": "GREEN",
"codeVerificationStatus": "VERIFIED"
},
{
"id": "567890123456789",
"displayPhoneNumber": "+44 20 7946 0958",
"verifiedName": "Acme Corp UK",
"qualityRating": "YELLOW",
"codeVerificationStatus": "VERIFIED"
}
],
"count": 2,
"status": "success"
}
Expression Reference
| Value | Expression | Notes |
|---|
| All phone numbers | {{ $output.listPhones.phoneNumbers }} | Pipe into a SplitInBatches node to process each number individually. |
| Total count | {{ $output.listPhones.count }} | Use to confirm at least one number is registered before proceeding. |
| First number ID | {{ $output.listPhones.phoneNumbers[0].id }} | Useful when the WABA has a single primary sending number. |
| Filter by quality | {{ $output.listPhones.phoneNumbers.filter(p => p.qualityRating === 'GREEN') }} | Use in a Function node to select only GREEN-rated numbers for campaign dispatch. |
Node Policies & GuardRails
| Policy Area | Recommendation |
|---|
| Credential storage | Store the access token in BizFirst Credentials Manager. |
| WABA ID management | Store the WABA ID as a workflow constant or environment variable rather than hardcoding it in each node configuration. |
| Paginated results | Meta may paginate results for WABAs with many numbers. Check rawResponse for a paging.cursors.after field and implement cursor-based pagination if needed. |
| Error port | Connect the error port. A 200 permission error is the most common failure for this operation — the System User token must include the WABA in its linked assets. |
| Caching | The phone number list changes infrequently. Cache the result in a workflow variable and refresh only when a provisioning event occurs rather than calling on every execution. |
Examples
Bulk Quality Rating Audit
{
"resource": "phone-number",
"operation": "list",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"wabaId": "987654321098765"
}
A Schedule trigger fires daily. This node retrieves all phone numbers. A SplitInBatches node iterates each entry. An IfCondition evaluates {{ $item.qualityRating }} — numbers rated RED are routed to a Function node that creates a ServiceNow incident for the operations team.
Dynamic Sender Selection for Campaign
{
"resource": "phone-number",
"operation": "list",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "{{ $env.PRIMARY_PHONE_ID }}",
"wabaId": "{{ $env.WABA_ID }}"
}
Before a campaign broadcasts, this node retrieves the number list. A Function node filters to numbers with qualityRating === "GREEN" and selects the first result as the sender ID. The downstream message/sendTemplate node uses this dynamic ID as its phoneNumberId.
