{
"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>"
},
"messengerApiError": {
"code": "100",
"subcode": "2018276"
}
}
}{
"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>"
},
"messengerApiError": {
"code": "100",
"subcode": "2018276"
}
}
}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>"
},
"messengerApiError": {
"code": "100",
"subcode": "2018276"
}
}
}{
"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>"
},
"messengerApiError": {
"code": "100",
"subcode": "2018276"
}
}
}Path Parameters
Phone number in E.164 format.
"+16315551111"
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 in E.164 format.
"+16315551111"
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 
