Business-scoped user IDs

Learn about using business-scoped user IDs with LATAM Messaging's WhatsApp channel

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

• Retrieve business-scoped user ID information from LATAM Messaging callbacks

• Manage how phone numbers and business-scoped user IDs relate to one another

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!"
          }
        }
      ]
    }
  }
}

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.

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.

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.

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:

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
}
}

Phone number

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:

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"
    }
  ]
}

Phone number

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 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.