BSUID Username Support FAQ

With Meta rolling out usernames and Business-Scoped User IDs (BSUID) — where a customer's wa_id (phone number) becomes conditional and the user_id (BSUID) is always present — this document answers common questions about ChakraHQ's support plan for webhook pass-through and the send API.

Webhook Pass-Through

1. Does ChakraHQ forward user_id (BSUID) and username in webhook payloads for inbound messages?

Yes Chakra already forwards BSUID (user_id) and username when the fields are available in Meta's original events for your customer and WABA

2. Does ChakraHQ forward user_id (BSUID) and username in status webhooks (sent/delivered/read)?

Yes Chakra already forwards BSUID (user_id) and username when the fields are available in Meta's original events for your customer and WABA

3. Will user_id (BSUID) and username be included in the list-chat-messages-for-phone-number response?

No. This API is meant to list chat messages for a phone number

Sending by BSUID

4. Does the send/reply endpoint accept a BSUID as the recipient identifier, instead of requiring a phone number?

The Pass through messages API supports recipient modifiers for sending session and template messages

The send template message for phone number will not support BSUID

5. Can a merchant reply to a username-only contact whose phone number is hidden?

The chakra chat inbox already supports messages and chats for contacts whose phone is hidden but BSUID is available

Timeline

6. When will webhook pass-through support for BSUID/username be available?

Chakra Chat already supports the new fields But meta is gradually rilling out the support across the globe. So if BSUID/usernames are available for your region / WABA then they will be available for you via Chakra Chat.

7. When will send-by-BSUID support be available?

Chakra Chat already supports sending of session and template messages via BSUID recipient. Please refer to "Sending By BSUID" section

8. Given LATAM's Meta rollout starting September 2026, will ChakraHQ's support be ready in time for that region?

Yes

`user_id_update` Event

9. Will ChakraHQ forward Meta's user_id_update webhook (triggered when a user's phone number change causes BSUID regeneration)?

No. user_id_update event is not available via webhooks yet.

10. What will the payload shape/structure of the forwarded user_id_update event look like?

user_id_update event is not available via Chakra Webhooks yet.

Field Naming

11. What field names will ChakraHQ use for BSUID and username in pass-through payloads?

The pass through webhook event structure is identical to Meta's raw webhook event structure. Specifically the following fields in the change event

contacts
- user_id — New property. Will be set to the user’s BSUID.
messages
- from_user_id — New property. Will be set to the user’s BSUID.

Sample event structure can be found here - https://apidocs.chakrahq.com/doc-919167#sample-inbound-text-message-event

12. Will ChakraHQ use Meta-native field names (contacts[].user_id, messages[].from_user_id) or custom/renamed fields (like Infobip's contact.userId)?

Yes, The pass through webhook event will use Meta-native field names

13. Where can we find documentation of the exact field names/schema so we can build our parser without guessing?