Skip to main content

WhatsApp Identity

WhatsApp lets people chat with businesses using a username instead of showing their phone number. For these customers WhatsApp gives the business a business-scoped user ID (BSUID) instead of a number. A BSUID starts with a two-letter country code and a dot, for example TR.2540988111111111.

MonoChat handles both kinds of customer. This page explains what you see in the chat screen and the CRM, and how MonoChat decides where a message goes.

How these customers appear​

When MonoChat knows the customer's phone number, nothing changes: the number is shown as before.

When there is no phone number, MonoChat shows, in this order:

  1. The customer's WhatsApp username, with an @ in front (for example @coffeelover). If the customer has several WhatsApp accounts, the most recently seen username is used.
  2. If there is no username, a masked BSUID that keeps the country prefix and the last four characters, for example TR.***1111.

The raw BSUID is never shown in the session list or the chat header. It is long, means nothing to an agent, and stays hidden from users who are not allowed to see customer identities.

Identity details on the customer profile​

MonoChat collects every phone number, BSUID and username it learns from incoming messages, delivery reports, contact cards and WhatsApp system notifications, and stores them on the customer's WhatsApp channel.

You can see them in two places:

  • CRM › customer › Profile › Customer Channels: click the arrow next to a WhatsApp channel (tooltip WhatsApp Identity) to expand the details.
  • Chat screen: the WhatsApp Identity widget on the right of a WhatsApp session.
FieldWhat it shows
Portfolio 1, 2, …Shown when the customer wrote to more than one Meta business portfolio; each has its own identity.
UsernameThe customer's WhatsApp username, or -.
Identity numberThe masked BSUID.
Parent identity numberThe masked parent BSUID, when WhatsApp sends one.
Phone NumberThe phone number, if known. An Unverified badge means the number may now belong to another WhatsApp account: "This number may now belong to another WhatsApp account; do not use it for calls."
Last SeenWhen MonoChat last saw this identity.
SourceWhere the information came from: Incoming message, Delivery report, Contact card or System notification.
Previous identitiesEarlier BSUIDs of the same customer, with a counter. Click to expand the list.
info

Seeing customer identities requires the Read customer identities in CRM for tenants permission. See Roles.

Which address MonoChat sends to​

When you, a flow or a bulk message writes to a WhatsApp customer, MonoChat picks the address in this order:

  1. A phone number it has collected for the customer that is not marked as unverified. Sending to the phone keeps WhatsApp's phone and BSUID mapping alive.
  2. The phone number the customer record was created with, as long as it has not been reassigned.
  3. The customer's BSUID (the most recently seen one).
  4. Otherwise, the customer's original address.

Reassigned numbers are skipped​

Phone numbers get recycled. When WhatsApp reports that a customer's number now belongs to a different account, MonoChat marks it Unverified and stops using it. If that number was the only address MonoChat knew, the message is not sent, so it cannot reach the number's new owner:

  • In the chat screen you get the error "The customer phone number was reassigned and no other address is known for this channel."
  • In a bulk message, the recipient's record is marked Failed (customerAddressUnreachable). See Bulk Messages.

Authentication templates need a phone number​

WhatsApp does not allow authentication templates (one-time codes) to be sent to a BSUID. If a customer has only a username identity, MonoChat stops the send with "Authentication templates cannot be sent to a BSUID address (Meta restriction)." In bulk messages the record fails with "Authentication templates require a phone number; this recipient only has a hidden-number WhatsApp identity".

Tips​

  • To learn a username customer's phone number, send a Contact Info Request message or use a template with a REQUEST_CONTACT_INFO button. See Message Types.
  • Do not call a number with the Unverified badge; it may reach a stranger.