{
"id": "1234567890123456",
"wabaId": "whatsapp-business-account-id",
"phoneNumber": "+16315551111",
"displayPhoneNumber": "+1 631-555-1111",
"businessUsername": "acme.support",
"businessUsernameStatus": "not_set",
"requestedBusinessUsername": "acme.help",
"businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z"
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
}
}
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
}
}
}Update a phone number business username
Requests a Business Username update for a WhatsApp business phone number.
The requested username may require Meta review before it becomes active. If Meta accepts or reserves the request for review, the response status is usually reserved; pending_review is kept only as a legacy compatibility value. If Meta returns an error, YCloud returns the error and does not change the stored Business Username state.
The username value is a plain username without @. YCloud trims leading and trailing whitespace and normalizes the value to lowercase before validation and submission.
{
"id": "1234567890123456",
"wabaId": "whatsapp-business-account-id",
"phoneNumber": "+16315551111",
"displayPhoneNumber": "+1 631-555-1111",
"businessUsername": "acme.support",
"businessUsernameStatus": "not_set",
"requestedBusinessUsername": "acme.help",
"businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z"
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
}
}
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
}
}
}Authorizations
Path Parameters
WhatsApp Business Account ID.
"whatsapp-business-account-id"
Body
Business Username to request for the phone number. Send the plain username without @.
YCloud trims leading and trailing whitespace and normalizes the value to lowercase before validation and submission. The value must be 3-35 characters, contain only English letters, numbers, periods, and underscores, and contain at least one English letter. It must not start or end with a period, contain consecutive periods, start with www, or end with common domain suffixes such as .com, .org, .net, .int, .edu, .gov, .mil, .us, .in, or .html.
3 - 35^[A-Za-z0-9._]+$"acme.support"
Response
Successfully submitted the update request.
Business Username state for a WhatsApp business phone number.
Phone number ID.
"1234567890123456"
WhatsApp Business Account ID.
"whatsapp-business-account-id"
Display phone number.
"+1 631-555-1111"
Active Business Username. The value is a plain username without @.
"acme.support"
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 usereserved. If an active username exists while a new request is reserved or under review,businessUsernameStatusisreserved,businessUsernamecontains the still-active username, andrequestedBusinessUsernamecontains the requested username.
not_set, active, pending_review, reserved Last requested Business Username that is still under review. This value can coexist with an active businessUsername while the new request is pending.
"acme.help"
The time when the Business Username state was last updated.
"2026-05-26T12:00:00.000Z"