# 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](/docs/conversation/processing-modes). 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 Conversation API 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 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: Business scoped user ID ``` { "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": {} } ``` Phone number ``` { "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_phone_number", "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: Business scoped user ID ``` { "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" } } } ``` Phone number ``` { "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_phone_number", "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", "phone_number": "CONTACT_phone_number", "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" } } } ``` Phone number (prior to update) ``` { "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_phone_number", "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" }, "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: Business scoped user ID ``` { "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" } } } ``` Phone number ``` { "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_phone_number", "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", "phone_number": "CONTACT_phone_number", "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" } } } ``` Phone number (prior to update) ``` { "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_phone_number", "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" }, "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: Business scoped user ID ``` { "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": "" } } } ``` Phone number ``` { "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_phone_number", "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", "phone_number": "CONTACT_phone_number", "user_id": "CONTACT_business_scoped_user_id", "parent_user_id": "PARENT_business_scoped_user_id" }, "sender_phone_number": "" } } } ``` Phone number (prior to update) ``` { "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_phone_number", "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", "profile_names": { "CONTACT_phone_number": "Full Name of WhatsApp User" }, "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: Business scoped user ID ``` { "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": "" } } } ``` Phone number ``` { "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_phone_number", "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", "phone_number": "CONTACT_phone_number", "user_id": "CONTACT_business_scoped_user_id", "parent_user_id": "PARENT_business_scoped_user_id" }, "sender_phone_number": "" } } } ``` Phone number (prior to update) ``` { "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_phone_number", "app_id": "" }, "accept_time": "2025-12-02T19:21:28.259249449Z", "processing_mode": "CONVERSATION" }, "message_metadata": "", "correlation_id": "", "channel_metadata": { "whatsapp": { "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](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 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](/assets/whatsapp_user_id_contact_book_phone_number.fc853cad3b3a6a55a7f113384217fbca59a1f1efc5a5fe25c432795245421d4a.3a8dbadf.png) 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](/assets/whatsapp_user_id_contact_book_bsuid.145d2ccd20b1bc96a9394b8c05cead2774b736bfbeed83d24ffdc2d25017326a.3a8dbadf.png)