--- title: "Register a phone number" method: POST path: "/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/register" tags: ["WhatsApp Phone Numbers"] --- # Register a phone number `POST /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/register` Registers a WhatsApp business phone number. ## Path parameters - `wabaId` string, required - `phoneNumber` string, required ## Response `200` Successfully registered the phone number. - WhatsappPhoneNumber — See [WhatsApp Business Phone Number](https://developers.facebook.com/docs/whatsapp/cloud-api/phone-numbers) - `id` string — Phone number ID. - `phoneNumber` string — Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. - `displayPhoneNumber` string — Display phone number. - `wabaId` string — WhatsApp Business Account ID. - `businessUsername` string — 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. - `requestedBusinessUsername` string — Last requested Business Username that is still under review. This value can coexist with an active `businessUsername` while the new request is pending. - `businessUsernameUpdatedAt` string, 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](https://www.facebook.com/business/help/896873687365001). - `GREEN`: High quality. - `YELLOW`: Medium quality. - `RED`: Low quality. - `UNKNOWN`: Unknown quality. - `messagingLimit` string — 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](https://developers.facebook.com/docs/whatsapp/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. - `whatsappBusinessManagerMessagingLimit` string — 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](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/reference/phone_number_quality_update). - `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. - `verifiedName` string — Verified name. - `codeVerificationStatus` 'VERIFIED' | 'NOT_VERIFIED' | 'EXPIRED' — To see if a phone number has been verified via OTP (one-time password). - `isOfficialBusinessAccount` boolean — 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](https://developers.facebook.com/docs/whatsapp/overview/business-accounts#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](https://developers.facebook.com/docs/whatsapp/business-management-api/manage-phone-numbers#get-display-name-status--beta-). - `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](https://developers.facebook.com/docs/whatsapp/business-management-api/manage-phone-numbers#get-display-name-status--beta-). - `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. - `requestedVerifiedName` string — Last requested verified name. - `rejectionReason` string — 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](https://www.facebook.com/business/help/896873687365001) 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. ## Other responses - `404` — The requested resource does not exist. --- [API](https://skmtc.dev/ycloud/apis/ycloud-api.md) · [All operations](https://skmtc.dev/ycloud/apis/ycloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ycloud/ycloud-api/revisions/4e13d3ca9df8/schema)