Sign in

v1

latestOpenAPI 3.0.02026-07-2491237338.9 KB
WhatsApp Phone Numbers

Register a phone number

Registers a WhatsApp business phone number.

post/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/register

Path parameters

wabaIdstring required
Example:whatsapp-business-account-id

WhatsApp Business Account ID.

phoneNumberstring required
Example:1234567890123456

Phone number ID.

Response

Successfully registered the phone number.

idstring

Phone number ID.

phoneNumberstring

Phone number in E.164 format.

displayPhoneNumberstring

Display phone number.

wabaIdstring

WhatsApp Business Account ID.

businessUsernamestring

Active Business Username for this phone number. The value is a plain username without @.

businessUsernameStatus'not_set' | 'active' | 'pending_review' | 'reserved'

Business Username state for a WhatsApp business phone number.

  • not_set: No active or pending Business Username exists.
  • active: A Business Username is active.
  • reserved: A requested Business Username is reserved by Meta and may still be under review.
  • pending_review: Legacy compatibility value for an under-review request. New writes use reserved. If an active username exists while a new request is reserved or under review, businessUsernameStatus is reserved, businessUsername contains the still-active username, and requestedBusinessUsername contains the requested username.
requestedBusinessUsernamestring

Last requested Business Username that is still under review. This value can coexist with an active businessUsername while the new request is pending.

businessUsernameUpdatedAtstring date-time

The time when the Business Username state was last updated.

qualityRating'GREEN' | 'YELLOW' | 'RED' | 'UNKNOWN'

Quality rating. One of GREEN, YELLOW, RED, or UNKNOWN. See also Phone Number Quality Rating.

  • GREEN: High quality.
  • YELLOW: Medium quality.
  • RED: Low quality.
  • UNKNOWN: Unknown quality.
messagingLimitstring

Messaging limits determine the maximum number of business-initiated conversations each phone number can start in a rolling 24-hour period. See also Messaging Limits.

  • TIER_NOT_SET: Unknown limit.
  • TIER_50: 50 business-initiated conversations in a rolling 24-hour period.
  • TIER_250: 250 business-initiated conversations in a rolling 24-hour period.
  • TIER_1K: 1K business-initiated conversations with unique customers in a rolling 24-hour period.
  • TIER_10K: 10K business-initiated conversations with unique customers in a rolling 24-hour period.
  • TIER_100K: 100K business-initiated conversations with unique customers in a rolling 24-hour period.
  • TIER_UNLIMITED: An unlimited number of business-initiated conversations in a rolling 24-hour period.
whatsappBusinessManagerMessagingLimitstring

The owning business portfolio's messaging limit. Starting October 7, 2025, messaging limits will instead be calculated and set on a business portfolio basis, and will be shared by all business phone numbers within each portfolio. See also phone_number_quality_update webhook reference.

  • TIER_NOT_SET: The business phone number has not been used to send a message yet.
  • TIER_50: Messaging limit of 50 business-initiated conversations in a rolling 24-hour period.
  • TIER_250: Messaging limit of 250 business-initiated conversations in a rolling 24-hour period.
  • TIER_2K: Messaging limit of 2,000 business-initiated conversations in a rolling 24-hour period.
  • TIER_10K: Messaging limit of 10,000 business-initiated conversations in a rolling 24-hour period.
  • TIER_100K: Messaging limit of 100,000 business-initiated conversations in a rolling 24-hour period.
  • TIER_UNLIMITED: The business phone number has higher throughput with unlimited business-initiated conversations.
verifiedNamestring

Verified name.

codeVerificationStatus'VERIFIED' | 'NOT_VERIFIED' | 'EXPIRED'

To see if a phone number has been verified via OTP (one-time password).

isOfficialBusinessAccountboolean

Whether this phone number is an official business account or not. An official business account has a green checkmark badge in its profile and chat thread headers. See Official Business Account for more information.

status'PENDING' | 'UNVERIFIED' | 'MANUAL_REVIEW' | 'DISCONNECTED' | 'CONNECTED' | 'FLAGGED' | 'WARNED' | 'RATE_LIMITED' | 'BANNED' | 'RESTRICTED' | 'BLOCKED' | 'MIGRATED' | 'UNKNOWN'

The status of a WhatsApp business phone number.

  • PENDING: Pending. Phone number is newly added. Verify and register this phone number so it can be connected to your account.
  • UNVERIFIED: Unverified. Verify this phone number to start sending messages.
  • MANUAL_REVIEW: Being reviewed. Phone number is currently being reviewed for connection to your account.
  • DISCONNECTED: Offline. Phone number is currently not reachable by WhatsApp servers.
  • CONNECTED: Connected. Phone number is associated with this account and working properly.
  • FLAGGED: Flagged. This phone number has been flagged due to low quality messages.
  • WARNED: Warned. A warning has been issued for this number, potentially due to spam reports.
  • RATE_LIMITED: Rate limited. The number of messages you can send from this phone number may be restricted.
  • BANNED: Banned. Phone number cannot be used with a WhatsApp account.
  • RESTRICTED: Restricted. This phone number has reached its 24-hour messaging limit and can no longer send messages to customers. Please wait until the messaging limit is reset to send messages.
  • BLOCKED: Message limit reached. The limit has been reached for this 24-hour period.
  • MIGRATED: Transferred. This phone number has been transferred to another WhatsApp Business account.
  • UNKNOWN: Unavailable. The status of this phone number can't be determined right now.
nameStatus'APPROVED' | 'AVAILABLE_WITHOUT_REVIEW' | 'DECLINED' | 'EXPIRED' | 'PENDING_REVIEW' | 'NONE'

The review status of the current display name request. See also Get Display Name Status.

  • APPROVED: The name has been approved. You can download your certificate now.
  • AVAILABLE_WITHOUT_REVIEW: The certificate for the phone is available and display name is ready to use without review.
  • DECLINED: The name has not been approved. You cannot download your certificate.
  • EXPIRED: Your certificate has expire and can no longer be downloaded.
  • PENDING_REVIEW: Your name request is under review. You cannot download your certificate.
  • NONE: No certificate is available.
newNameStatus'APPROVED' | 'AVAILABLE_WITHOUT_REVIEW' | 'DECLINED' | 'EXPIRED' | 'PENDING_REVIEW' | 'NONE'

The review status of the current display name request. See also Get Display Name Status.

  • APPROVED: The name has been approved. You can download your certificate now.
  • AVAILABLE_WITHOUT_REVIEW: The certificate for the phone is available and display name is ready to use without review.
  • DECLINED: The name has not been approved. You cannot download your certificate.
  • EXPIRED: Your certificate has expire and can no longer be downloaded.
  • PENDING_REVIEW: Your name request is under review. You cannot download your certificate.
  • NONE: No certificate is available.
decision'APPROVED' | 'REJECTED'

Used if a decision about WhatsApp accounts or phone numbers has been made.

requestedVerifiedNamestring

Last requested verified name.

rejectionReasonstring

Rejection reason.

qualityUpdateEvent'ONBOARDING' | 'UPGRADE' | 'DOWNGRADE' | 'FLAGGED' | 'UNFLAGGED'

Indicates the update event type of WhatsApp phone number quality when a notification is sent to you.

  • ONBOARDING: Typically when the messaging limit changes from TIER_NOT_SET to another tier.
  • UPGRADE: Messaging limit tier upgraded.
  • DOWNGRADE: Messaging limit tier downgraded.
  • FLAGGED: Flagged status occurs when the quality rating reaches a low state. If the message quality improves to a high or medium state and maintains this for 7 days, your status will return to Connected. If the quality rating doesn't improve, your status will still return to Connected, but you'll be placed in a lower messaging limit tier. Learn more on Phone Number Quality Rating docs.
  • UNFLAGGED: Phone number status changes from FLAGGED to CONNECTED.
updateEvent'ACCOUNT_RECONNECTED' | 'ACCOUNT_OFFBOARDED'

Account update event that triggered this phone number status change.

throughputLevel'STANDARD' | 'HIGH' | 'NOT_APPLICABLE'

Current Meta throughput level of the WhatsApp phone number.

  • STANDARD: Default Cloud API throughput level, currently up to 80 messages per second.
  • HIGH: Upgraded Cloud API throughput level, currently up to 1,000 messages per second, subject to Meta's current Cloud API throughput rules.
  • NOT_APPLICABLE: Throughput level is not applicable to this phone number.

Example response

{
  "id": "1234567890123456",
  "phoneNumber": "+16315551111",
  "displayPhoneNumber": "+1 631-555-1111",
  "wabaId": "whatsapp-business-account-id",
  "businessUsername": "acme.support",
  "requestedBusinessUsername": "acme.help",
  "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z",
  "messagingLimit": "TIER_1K",
  "verifiedName": "John’s Cake Shop",
  "updateEvent": "ACCOUNT_OFFBOARDED",
  "throughputLevel": "HIGH"
}