Troubleshooting

Troubleshooting

Known limitations of BSUID support and the most common failures when sending to a username-only customer.

Known limitations

• The one tap, zero tap and copy code authentication templates require a phone number. Meta does not deliver them to a customer identified only by a username.
• Sensitive messages are relayed without the BSUID.
• The BSUID is scoped to a single business portfolio. A sender from another portfolio cannot message it.
• The BSUID is regenerated when the user changes their phone number.
• Parent BSUIDs work across enrolled portfolios, but require prior approval from Meta.
• BSUID applies to WhatsApp only. SMS and RCS always require a phone number.

Common failures

Situation	Cause	Fix
The send is rejected as an invalid recipient	The BSUID is malformed or exceeds 135 characters	Check the full {ISO-2}.{alphanumeric} format — see Recipient Identifiers
The send fails even though the BSUID looks valid	The BSUID belongs to another business portfolio, or the user changed number and the identifier was regenerated	Use the BSUID from the most recent event you received
The event arrives with no To / From	The conversation is held over a username only	Read ToBsuid / FromBsuid — see BSUID in Webhooks
My system fails while processing an inbound event	It assumes the phone number is always present	Make the phone number optional and use the BSUID as the identifier
A stored BSUID stopped working	The user changed their phone number and the BSUID was regenerated	Update it with the one carried by the most recent event
The full contact card does not arrive	The customer replied to the button (Origin = contact_request)	Expected behaviour: use the phone number, which does arrive
An authentication template is not delivered	One tap, zero tap and copy code require a phone number	Request the phone number with a Share contact info template and retry