Handle BSUID-Only Users with the WhatsApp APIs

When a WhatsApp user adopts a username, they can message you without sharing a phone number, for example through Click-to-WhatsApp (CTWA) ads or a chat the user started. This user has a BSUID (Business-Scoped User ID) but no phone number. Integrations that only use phone numbers cannot reply to these users.

This guide shows how to receive, store, and use the BSUID with the WhatsApp APIs, so your third-party chatbot or custom integration can reply to them. To learn what a BSUID is and how Insider One uses it, see WhatsApp Usernames and the BSUID.

BSUID-based sending is enabled per account. If it is not enabled, Insider One ignores recipient and sends the message by phone number only, so a message with only a BSUID cannot be delivered. Contact the Insider One team to enable BSUID-based sending for your account.

In this guide, you will learn how to:

Receive BSUID data

Your webhook receives the BSUID in two places:

Inbound messages (user replies): read contacts[].user_id. Also read contacts[].wa_id, the phone number, which is empty when the user did not share it.
Delivered and read events: read statuses[].recipient_user_id.

The following abridged sample shows an inbound message from a user who has not shared a phone number.

{
  "entry": [
    {
      "changes": [
        {
          "field": "messages",
          "value": {
            "contacts": [
              {
                "profile": {
                  "name": "Jane",
                  "username": "jane_doe"
                },
                "wa_id": "",
                "user_id": "TR.2124566744990207"
              }
            ],
            "messages": [
              {
                "id": "{{MESSAGE_ID}}",
                "timestamp": "1755072000",
                "text": {
                  "body": "{{MESSAGE_BODY}}"
                },
                "type": "text"
              }
            ]
          }
        }
      ]
    }
  ]
}

The following sample shows the BSUID in a delivered status event.

"statuses": [
  {
    "id": "{{MESSAGE_ID}}",
    "recipient_id": "{{PHONE_NUMBER}}",
    "recipient_user_id": "TR.2124566744990207",
    "status": "delivered",
    "timestamp": "1755072000"
  }
]

For all fields, see Webhooks for Conversational WhatsApp and Webhooks for Transactional WhatsApp.

Store user identifiers

Key your sessions by both the phone number and the BSUID. When wa_id is empty, the BSUID is the only identifier you have for the user. Insider One also stores the BSUID on the user profile automatically, in the whatsapp_business_user_id attribute.

Reply to BSUID-only users

Call the Conversational API and set recipient to the BSUID. Send at least one of phoneNumber or recipient.

curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.**************************' \
--data '{
   "messages": [
       {
           "recipient": "TR.2124566744990207",
           "message": {
               "type": "text",
               "text": {
                   "preview_url": true,
                   "body": "Example Message"
               }
           }
       }
   ]
}'

You can also send template messages by BSUID through the Transactional API with the same recipient field. For all parameters, see Send Conversational WhatsApp Text Message and Send Transactional WhatsApp Template Message.

Handle BSUID changes

A user's BSUID can change. Insider One forwards a system message to your webhook in two cases:

user_changed_user_id: The BSUID changed on its own.
user_changed_number: The user changed their phone number, which also creates a new BSUID.

In both cases, move your stored state from system.previous_user_id to the new contacts[].user_id. Insider One updates the user profile itself. For the payload, see BSUID change events.

Request the phone number

When you need the phone number, send a template with the Request Contact Info button. The number the user shares is stored on their profile automatically. For more information, see WhatsApp Usernames and the BSUID.

Troubleshoot errors

Error	What it means	What to do
131026	The BSUID is invalid.	Check the format: an ISO country code, a dot, and an ID, such as `TR.ABC123`.
20030	The country is not contracted. Insider One checks the country prefix of the BSUID.	Send to a BSUID whose country prefix is on your contracted countries list.
Request-time validation error	The request has neither `phoneNumber` nor `recipient`.	Send at least one of the two.

Conclusion

To reply to a user who has only a BSUID, read user_id from the webhook, store it next to the phone number, and send it as recipient. Update your stored BSUID whenever a system message reports a change. If replies still go out by phone number only, contact the Insider One team to confirm that BSUID-based sending is enabled for your account.