Skip to content
Conversation API/Channels/
/
Business-scoped user ID s...
Last updated

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. Conversation API customers may use this business-scoped user ID to identify recipients when using Conversation API. Additionally, for some contacts that adopt usernames later in 2026, the busienss-scoped user IDs may be the only identifier available. Business-scoped user ID information will begin to be included in Conversation API callbacks in March of 2026.

When using Conversation API, you are able to identify your message recipients by channel and identity pairs. For WhatsApp, the channel value is always WHATSAPP and the identity 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 identity values when specifying your recipient in Conversation API calls. You can collect business-scoped user IDs from certain Conversation API callbacks, which will be updated to include these business-scoped user IDs.

Note:

WhatsApp business-scoped user IDs are not the same value as Conversation API contact IDs. Conversation API contact IDs, when known, can be used to as an alternative to channel and identity pairs when identifying contacts using CONVERSATION mode.

In order to successfully make use of WhatsApp business-scoped user IDs, you must know how to:

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 Conversation API call that identifies recipients through channel and identity pairs. 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:

{
    "app_id": "YOUR_app_id",
    "recipient": {
        "identified_by": {
            "channel_identities": [
                {
                    "channel": "WHATSAPP",
                    "identity": "CONTACT_business_scoped_user_id"
                }
            ]
        }
    },
    "message": {
        "text_message": {
            "text": "Hello from Sinch."
        }
    }
}
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 delivery report will have a code of CHANNEL_FAILURE with a description of The underlying channel reported: You can only send authentication messages to recipients' phone numbers, not their business-scoped user IDs.

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 infromation may be included in different Conversation API webhooks, including webhooks that make use of channel and identity pairs. This is especially true for the MESSAGE_DELIVERY, MESSAGE_INBOUND, and EVENT_INBOUND webhooks. This information will begin to be included in Conversation API webhooks in March of 2026.

Note:

If, for any reason, Conversation API is able associate a contact with a phone number, the phone number will be included as the identity in the channel and identity pair.

Business-scoped user ID information in the MESSAGE_DELIVERY webhooks

If you send a message to a recipient after March of 2026, MESSAGE_DELIVERY callbacks (i.e., delivery reports) may include business-scoped user ID information. Below are examples of delivery reports for QUEUED_ON_CHANNEL, DELIVERED, and READ message delivery statuses.

Business-scoped user ID information in QUEUED_ON_CHANNEL delivery reports

Below are examples of delivery reports with a QUEUED_ON_CHANNEL status. 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 identity field:

{
  "app_id": "01JERBD8W3YRTA0DV4V76X429D",
  "accepted_time": "2025-11-26T17:23:08.614Z",
  "event_time": "2025-11-26T17:23:09.657218958Z",
  "project_id": "2cb92b1b-2faf-40be-9380-accec4f24f46",
  "message_delivery_report": {
    "message_id": "01KB0K1FP6HTG4W9EJV6YYFH3G",
    "conversation_id": "01JQ6RN9DTAMF5HXBZKQE90WXT",
    "status": "QUEUED_ON_CHANNEL",
    "channel_identity": {
      "channel": "WHATSAPP",
      "identity": "CONTACT_business_scoped_user_id",
      "app_id": ""
    },
    "contact_id": "01JQ6RN90Q6EG6ES4V9W5SQVVV",
    "metadata": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": "",
  "correlation_id": "",
  "channel_metadata": {}
}

Note that the only difference between the two callbacks is the identity value.

Business-scoped user ID information in DELIVERED delivery reports

Below are examples of delivery reports with a DELIVERED status. The tab that is selected by default displays a delivery report that was sent using a business-scoped user ID (one unassociated with a phone number). The second tab displays a delivery report for a message sent to a contact that is associated with a phone number in your Conversation API solution. The third tab includes an example of how the callback looked prior to this update and, therefore, contains no business-scoped user ID information:

{
  "app_id": "01JERBD8W3YRTA0DV4V76X429D",
  "accepted_time": "2025-11-26T17:23:08.614Z",
  "event_time": "2025-11-26T17:23:13Z",
  "project_id": "2cb92b1b-2faf-40be-9380-accec4f24f46",
  "message_delivery_report": {
    "message_id": "01KB0K1FP6HTG4W9EJV6YYFH3G",
    "conversation_id": "01JQ6RN9DTAMF5HXBZKQE90WXT",
    "status": "DELIVERED",
    "channel_identity": {
      "channel": "WHATSAPP",
      "identity": "CONTACT_business_scoped_user_id",
      "app_id": ""
    },
    "contact_id": "01JQ6RN90Q6EG6ES4V9W5SQVVV",
    "metadata": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": "{\"pricing_category\":\"utility\",\"whatsapp_conversation_id\":\"37e3cca81c3cb87beb3352ad321ad1a2\",\"pricing_type\":\"regular\"}",
  "correlation_id": "",
  "channel_metadata": {
    "whatsapp": {
      "conversation": {
        "type": "utility"
      },
      "user_profile": {
        "display_name": "CONTACT_display_name",
        "username": "CONTACT_username",
        "country_code": "CONTACT_country_code",         
        "user_id": "CONTACT_business_scoped_user_id",
        "parent_user_id": "PARENT_business_scoped_user_id"               
      },                                                
      "sender_phone_number": "46790647884",
      "pricing": {
        "model": "PMP",
        "type": "regular"
      },
      "template_id": "775168995141151"
    }
  }
}

The differences between the delivery reports are described below:

  • The business-scoped user ID delivery report includes the business-scoped user ID in the identity field of the channel and identity pair. The phone number delivery reports include the phone number in the identity field of the channel and identity pair.
  • The new delivery reports include a user_profile object of the following form:
    "user_profile": {
  "display_name": "CONTACT_display_name",
  "username": "CONTACT_username",
  "country_code": "CONTACT_country_code",
  "phone_number": "CONTACT_phone_number",
  "user_id": "CONTACT_business_scoped_user_id",
  "parent_user_id": "PARENT_business_scoped_user_id"
}
    Note that the phone_number field will not be included if this delivery report corresponds to a contact for which there is no phone number information.

Business-scoped user ID information in READ delivery reports

Below are examples of delivery reports with a READ status. The tab that is selected by default displays a delivery report for a message sent using a business-scoped user ID (one unassociated with a phone number). The second tab displays a delivery report for a message sent to a contact that is associated with a phone number in your Conversation API solution. The third tab includes an example of how the callback looked prior to this update and, therefore, contains no business-scoped user ID information:

{
  "app_id": "01JERBD8W3YRTA0DV4V76X429D",
  "accepted_time": "2025-11-26T17:23:08.614Z",
  "event_time": "2025-11-26T17:23:16Z",
  "project_id": "2cb92b1b-2faf-40be-9380-accec4f24f46",
  "message_delivery_report": {
    "message_id": "01KB0K1FP6HTG4W9EJV6YYFH3G",
    "conversation_id": "01JQ6RN9DTAMF5HXBZKQE90WXT",
    "status": "READ",
    "channel_identity": {
      "channel": "WHATSAPP",
      "identity": "CONTACT_business_scoped_user_id",
      "app_id": ""
    },
    "contact_id": "01JQ6RN90Q6EG6ES4V9W5SQVVV",
    "metadata": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": "{\"pricing_category\":\"utility\",\"whatsapp_conversation_id\":\"37e3cca81c3cb87beb3352ad321ad1a2\",\"pricing_type\":\"regular\"}",
  "correlation_id": "",
  "channel_metadata": {
    "whatsapp": {
      "conversation": {
        "type": "utility"
      },
      "user_profile": {
        "display_name": "CONTACT_display_name",
        "username": "CONTACT_username",
        "country_code": "CONTACT_country_code",
        "user_id": "CONTACT_business_scoped_user_id",
        "parent_user_id": "PARENT_business_scoped_user_id"
      },  
      "sender_phone_number": "46790647884",
      "pricing": {
          "model": "PMP",
          "type": "regular"
      },
      "template_id": "775168995141151"
    }
  }
}

The differences between the delivery reports are described below:

  • The business-scoped user ID delivery report includes the business-scoped user ID in the identity field of the channel and identity pair. The phone number delivery reports include the phone number in the identity field of the channel and identity pair.
  • The new delivery reports include a user_profile object of the following form:
    "user_profile": {
  "display_name": "CONTACT_display_name",
  "username": "CONTACT_username",
  "country_code": "CONTACT_country_code",
  "phone_number": "CONTACT_phone_number",
  "user_id": "CONTACT_business_scoped_user_id",
  "parent_user_id": "PARENT_business_scoped_user_id"
}
    Note that the phone_number field will not be included if this delivery report corresponds to a contact for which there is no phone number information.

Business-scoped user ID information in the MESSAGE_INBOUND 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 second tab displays an inbound message from a contact associated with a phone number in your Conversation API solution. The third tab includes an example of how the callback looked prior to this update and, therefore, contains no business-scoped user ID information:

{
  "app_id": "01JERBD8W3YRTA0DV4V76X429D",
  "accepted_time": "2025-11-26T14:58:24.765Z",
  "event_time": "2025-11-26T14:58:20Z",
  "project_id": "2cb92b1b-2faf-40be-9380-accec4f24f46",
  "message": {
    "id": "01KB0ARFBXZV1JDH4D5HWGQRTB",
    "direction": "TO_APP",
    "contact_message": {
      "text_message": {
        "text": "Hello"
      }
    },
    "channel_identity": {
      "channel": "WHATSAPP",
      "identity": "CONTACT_business_scoped_user_id",
      "app_id": ""
    },
    "conversation_id": "01JTV3W97M2QXDA66VJ3VZ0XYB",
    "contact_id": "01JTV3W8X8TRXT7QF3A1XMH2XD",
    "metadata": "",
    "accept_time": "2025-11-26T14:58:24.765Z",
    "sender_id": "44035667-a5c0-4dea-9205-82c44daee1fc",
    "processing_mode": "CONVERSATION",
    "injected": false
  },
  "message_metadata": "",
  "correlation_id": "",
  "channel_metadata": {
    "whatsapp": {
      "message_type": "text",
      "user_profile": {
        "display_name": "CONTACT_display_name",
        "username": "CONTACT_username",
        "country_code": "CONTACT_country_code",
        "user_id": "CONTACT_business_scoped_user_id",
        "parent_user_id": "PARENT_business_scoped_user_id"
      },
      "sender_phone_number": ""
    }
  }
}

Note the following:

  • The business-scoped user ID inbound message includes the business-scoped user ID in the identity field of the channel and identity pair. The phone number inbound messages include the phone number in the identity field of the channel and identity pair.
  • In both of the updated cases, a user_profile object of the following form is included:
    "user_profile": {
  "display_name": "CONTACT_display_name",
  "username": "CONTACT_username",
  "country_code": "CONTACT_country_code",
  "phone_number": "CONTACT_phone_number",    
  "user_id": "CONTACT_business_scoped_user_id",
  "parent_user_id": "PARENT_business_scoped_user_id"
}
    This will replace the profile_names object included in the callback that existed prior to the update, which is scheduled for deprecation:
    "profile_names": {  
    "CONTACT_phone_number": "Full Name of WhatsApp User"
},
    Note that the phone_number field will not be included if this delivery report corresponds to a contact for which there is no phone number information.

Business-scoped user ID information in the EVENT_INBOUND webhook

Below are examples of inbound event callbacks. The tab that is selected by default displays an inbound event associated with a WhatsApp contact with a username and no associated phone number. The second tab displays an inbound event associated with a user that is associated with a phone number in your Conversation API solution. The third tab includes an example of how the callback looked prior to this update and, therefore, contains no business-scoped user ID information:

{
  "app_id": "01JERBD8W3YRTA0DV4V76X429D",
  "event_time": "2025-12-02T19:21:28.138527270Z",
  "project_id": "2cb92b1b-2faf-40be-9380-accec4f24f46",
  "event": {
    "direction": "TO_APP",
    "contact_event": {
      "channel_specific_event": {
        "whatsapp_user_preferences_event": {
          "category": "marketing_messages",
          "preference": "stop"
        }
      }
    },
    "id": "01KBG86EV5SQ5R9QECCQE7GDX6",
    "conversation_id": "01JQ6RN9DTAMF5HXBZKQE90WXT",
    "contact_id": "01JQ6RN90Q6EG6ES4V9W5SQVVV",
    "channel_identity": {
      "channel": "WHATSAPP",
      "identity": "CONTACT_business_scoped_user_id",
      "app_id": ""
    },
    "accept_time": "2025-12-02T19:21:28.259249449Z",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": "",
  "correlation_id": "",
  "channel_metadata": {
    "whatsapp": {
      "user_profile": {
        "display_name": "CONTACT_display_name",
        "username": "CONTACT_username",
        "country_code": "CONTACT_country_code",
        "user_id": "CONTACT_business_scoped_user_id",
        "parent_user_id": "PARENT_business_scoped_user_id"
      },
      "sender_phone_number": ""
    }
  }
}

Note the following:

  • The business-scoped user ID inbound event includes the business-scoped user ID in the identity field of the channel and identity pair. The phone number inbound event includes the phone number in the identity field of the channel and identity pair.
  • In the updated callbacks, a user_profile object of the following form is included:
    "user_profile": {
  "display_name": "CONTACT_display_name",
  "username": "CONTACT_username",
  "country_code": "CONTACT_country_code",
  "phone_number": "CONTACT_phone_number",    
  "user_id": "CONTACT_business_scoped_user_id",
  "parent_user_id": "PARENT_business_scoped_user_id"
}
    Note that the phone_number field will not be included if this delivery report corresponds to a contact for which there is no phone number information.

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

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 Conversation API solution.

WhatsApp user ID contact book phone number flow

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

WhatsApp user ID contact book BSUID flow

Previous page
Next page