# Business-scoped user IDs In mid-2026, Meta will allow WhatsApp users to adopt usernames. Prior to this feature rollout, WhatsApp users will be assigned a corresponding business-scoped user ID. LATAM Messaging customers may use this business-scoped user ID to identify recipients when using LATAM Messaging. Additionally, for some contacts that adopt usernames later in 2026, the business-scoped user IDs may be the only identifier available. Business-scoped user ID information will begin to be included in LATAM Messaging callbacks in March of 2026. When using LATAM Messaging, you are able to identify your message recipients by setting the `destination`. The `destination` value has historically been a phone number. With the release of WhatsApp's business-scoped user ID functionality, you will also be able to use business-scoped user IDs as identifiers. These will take the form of `CONTACT_country_code.unique_alphanumeric_string` (for example, `US.13491208655302741918`) as `destination` values when specifying your recipient in LATAM Messaging calls. You can collect business-scoped user IDs from certain LATAM Messaging callbacks, which will be updated to include these business-scoped user IDs. In order to successfully make use of WhatsApp business-scoped user IDs, you must know how to: * [Incorporate business-scoped user IDs into your API calls](#including-business-scoped-user-ids-in-api-calls) * [Retrieve business-scoped user ID information from LATAM Messaging callbacks](#retrieving-business-scoped-user-id-information-from-callbacks) * [Manage how phone numbers and business-scoped user IDs relate to one another](#managing-phone-numbers-and-business-scoped-user-ids-using-contact-book) ### Including business-scoped user IDs in API calls If you already know your contact's business-scoped user ID, you may use it to identify them in any LATAM Messaging call that identifies recipients through the `destination` field. For example, to send a message to a recipient using their business-scoped user ID as identification, you would use a payload of the following form: ``` { "destinations": [ { "destination": "CONTACT_business_scoped_user_ID" } ], "message": { "button": { "body": { "text": "Hello from Latam API! I'm the body text." }, "footer": { "text": "Hello from Latam API! I'm the footer text." }, "buttons": [ { "reply": { "title": "I'm the title!", "payload": "I'm the payload!" } } ] } } } ``` {% hint style="info" %} Note the following: * Business-scoped user IDs are unique for each contact and are scoped to individual business service providers. Attempts to reach a contact through one business service provider by using a corresponding business-scoped user ID retrieved from another business service provider will fail. * You cannot use business-scoped user IDs to send one-tap, zero-tap, or copy code authentication template messages. If you attempt to send one of these messages using a business-scoped user ID, the corresponding status report will have a `sentStatus` of `CARRIER_COMMUNICATION_ERROR`. {% endhint %} The immediate response you receive after making your API call will be the same regardless of whether you use phone numbers of business-scoped user IDs to send the message. ### Retrieving business-scoped user ID information from callbacks Business-scoped user ID information may be included in different LATAM Messaging webhooks, including webhooks that make use of the `destination` field (for example, status webhooks) or the `source` field (for example, message inbound webhooks). This information will begin to be included in LATAM Messaging webhooks in March of 2026. {% hint style="info" %} Note: If, for any reason, LATAM Messaging is able associate a contact with a phone number, the phone number will be included as the `destination` or `source` value for webhooks associated with that contact. {% endhint %} Additional information will be included in the `userProfile` object. A description of this object, along with webhook examples, are provided in the subsections below. #### Business-scoped user ID information in the status webhooks If you send a message to a recipient after March of 2026, status callbacks (i.e., delivery reports) will include business-scoped user ID information. Below are examples of status webhooks. The tab that is selected by default displays a delivery report for a message sent using a business-scoped user ID. The alternate tab displays a delivery report for a message sent using a recipient's phone number and, therefore, does not include business-scoped user ID information in the `destination` field: {% tabs %} {% tab title="Business scoped user ID" %} ``` { "total": 1, "data": [ { "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91", "correlationId": "...", "destination": "CONTACT_business_scoped_user_ID", "userProfile": { "name": "CONTACT_name", "username": "CONTACT_username", "countryCode": "BR", "userId": "CONTACT_business_scoped_user_ID", "parentUserId": "PARENT_business_scoped_user_ID" }, "origin": "YOUR_phone_number", "campaignId": 100, "campaignAlias": "...", "flowId": "...", "extraInfo": "...", "sent": true, "sentStatusCode": 1, "sentStatus": "sent status", "sentDate": "2017-12-18T17:09:31.891Z", "sentAt": 1513616971891, "delivered": true, "deliveredStatusCode": 1, "deliveredStatus": "delivered status", "deliveredDate": "2017-12-18T17:09:31.891Z", "deliveredAt": 1513616971891, "read": true, "readDate": "2017-12-18T17:09:31.891Z", "readAt": 1513616971891, "updatedDate": "2017-12-18T17:09:31.891Z", "updatedAt": 1513616971891, "type": "MESSAGE", "conversation": { "id": "conversationId123", "origin": { "type": "REFERRAL_CONVERSION" }, "expiration": "2017-12-19T17:09:31.891Z" } } ], "clientInfo": { "customerId": 42, "subAccountId": 1291, "userId": 1 } } ``` {% endtab %} {% tab title="Phone number" %} ``` { "total": 1, "data": [ { "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91", "correlationId": "...", "destination": "CONTACT_phone_number", "userProfile": { "name": "CONTACT_name", "username": "CONTACT_username", "countryCode": "BR", "phoneNumber": "CONTACT_phone_number", "userId": "CONTACT_business_scoped_user_ID", "parentUserId": "PARENT_business_scoped_user_ID" }, "origin": "YOUR_phone_number", "campaignId": 100, "campaignAlias": "...", "flowId": "...", "extraInfo": "...", "sent": true, "sentStatusCode": 1, "sentStatus": "sent status", "sentDate": "2017-12-18T17:09:31.891Z", "sentAt": 1513616971891, "delivered": true, "deliveredStatusCode": 1, "deliveredStatus": "delivered status", "deliveredDate": "2017-12-18T17:09:31.891Z", "deliveredAt": 1513616971891, "read": true, "readDate": "2017-12-18T17:09:31.891Z", "readAt": 1513616971891, "updatedDate": "2017-12-18T17:09:31.891Z", "updatedAt": 1513616971891, "type": "MESSAGE", "conversation": { "id": "conversationId123", "origin": { "type": "REFERRAL_CONVERSION" }, "expiration": "2017-12-19T17:09:31.891Z" } } ], "clientInfo": { "customerId": 42, "subAccountId": 1291, "userId": 1 } } ``` {% endtab %} {% endtabs %} Note the following: * The callback includes new information in the `userProfile` object. The existing field (`name`) and each new field (`username`, `countryCode`, `phoneNumber`, `userId`, and `parentUserId`) are described in the table below:
| Field | Required? | Description | | -------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `username` | No | The username is included if the end-user activates the username feature. | | `countryCode` | Yes (`countryCode` will begin appearing in webhooks starting March 31, 2026). | Present when `userId` BSUID is set; its value is the first two characters of the BSUID containing the country code. | | `phoneNumber` | No | The MSISDN (phone number) of the contact. Because contacts can be identified using the business-scoped user ID, this field is not required. | | `userId` | Yes (business-scoped user IDs will begin appearing in webhooks starting March 31, 2026) | The business-scoped user ID. | | `parentUserId` | No | Parent business-scoped user IDs can be used in place of regular businses-scoped user IDs to message users. Functionally, parent business-scoped user IDs have the same properties as regular business-scoped user IDs, but they can be used by any business phone number within a given set of linked portfolios. | * The `phoneNumber` field of the `userProfile` object is **not** included in the business-scoped user ID example. If the phone number for that contact was known, it would be set as the `destination` *and* included in the `userProfile` object. * Because the phone number of the contact is known in the phone number example, the `destination` is set to the phone number. The business-scoped user ID is included in the `userId` field of the `userProfile` object. #### Business-scoped user ID information in the inbound messages webhook Below are examples of inbound message callbacks. The tab that is selected by default displays an inbound message received from a WhatsApp contact with a username and no associated phone number. The alternate tab displays an inbound message from a contact associated with a phone number in your LATAM Messaging solution: {% tabs %} {% tab title="Business scoped user ID" %} ``` { "total": 1, "data": [ { "id": "ce425ffe-bc62-421f-9261-e6819a5eab43", "source": "CONTACT_business_scoped_user_ID", "origin": "...", "userProfile": { "name": "CONTACT_name", "username": "CONTACT_username, "countryCode": "BR", "userId": "CONTACT_business_scoped_user_ID", "parentUserId": "CONTACT_business_scoped_user_ID" }, "campaignId": 100, "correlationId": "...", "campaignAlias": "...", "flowId": "....", "extraInfo": "...", "message": { "type": "TEXT", "messageText": "Hi, this is a message from the contact" }, "receivedAt": 1513616971473, "receivedDate": "2017-12-18T17:09:31.473Z" } ] } ``` {% endtab %} {% tab title="Phone number" %} ``` { "total": 1, "data": [ { "id": "ce425ffe-bc62-421f-9261-e6819a5eab43", "source": "CONTACT_phone_number", "origin": "...", "userProfile": { "name": "CONTACT_name", "username": "CONTACT_username, "countryCode": "BR", "phoneNumber": "CONTACT_phone_number" "userId": "CONTACT_business_scoped_user_ID", "parentUserId": "CONTACT_business_scoped_user_ID" }, "campaignId": 100, "correlationId": "...", "campaignAlias": "...", "flowId": "....", "extraInfo": "...", "message": { "type": "TEXT", "messageText": "Hi, this is a message from the contact" }, "receivedAt": 1513616971473, "receivedDate": "2017-12-18T17:09:31.473Z" } ] } ``` {% endtab %} {% endtabs %} Note the following: * The callback includes new information in the `userProfile` object. The existing field (`name`) and each new field (`username`, `countryCode`, `phoneNumber`, `userId`, and `parentUserId`) are described in the table below:
| Field | Required? | Description | | -------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `username` | No | The username is included if the end-user activates the username feature. | | `countryCode` | Yes (`countryCode` will begin appearing in webhooks starting March 31, 2026). | Present when `userId` BSUID is set; its value is the first two characters of the BSUID containing the country code. | | `phoneNumber` | No | The MSISDN (phone number) of the contact. Because contacts can be identified using the business-scoped user ID, this field is not required. | | `userId` | Yes (business-scoped user IDs will begin appearing in webhooks starting March 31, 2026) | The business-scoped user ID. | | `parentUserId` | No | Parent business-scoped user IDs can be used in place of regular businses-scoped user IDs to message users. Functionally, parent business-scoped user IDs have the same properties as regular business-scoped user IDs, but they can be used by any business phone number within a given set of linked portfolios. | * The `phoneNumber` field of the `userProfile` object is **not** included in the business-scoped user ID example. If the phone number for that contact was known, it would be set as the `source` *and* included in the `userProfile` object. * Because the phone number of the contact is known in the phone number example, the `source` is set to the phone number. The business-scoped user ID is included in the `userId` field of the `userProfile` object. ### Managing phone numbers and business-scoped user IDs using contact book Beginning in early April 2026, Meta will release a [contact book feature](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#contact-book) that will automatically collect and associate business-scoped user IDs with phone numbers for contacts to whom you have sent or from whom you have received a message using the contact's telephone number. This association will be passed to LATAM Messaging. Therefore, any contact you communicate with via phone number will, from that point on, be associated with the phone number and corresponding business-scoped user ID in your LATAM Messaging solution.
Following the release of this feature, we recommend sending out at least one MT message to each of your contacts using that contact's phone number. This will create an entry in Meta's contact book functionality and, therefore, facilitate easy continuity of communication between you and that contact going forward. If you receive an MO message from a contact that has adopted a username and is **not** associated with a phone number in your LATAM Messaging solution, that contact will not be associated with a phone number and the callbacks related to that contact will only include business-scoped user ID identification information.
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs-latam.messaging.sinch.com/whatsapp/business-scoped-user-ids.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.