1.1 Portfolio scoping

The three are easy to conflate, and the portfolio sits above the other two. One portfolio can own several WABAs, and each WABA can have several phone numbers. A person who messages your support number and your notifications number gets the same BSUID, even if those numbers belong to different WABAs, as long as the same portfolio owns them. If the same person messages a number that belongs to a different portfolio of yours, they get a different BSUID.

Note that this is the opposite of the 30-day phone number rule from Chapter 0.2: the identifier is portfolio-wide, but the fallback that keeps phone numbers arriving is evaluated per business phone number.

What follows from scoping

A BSUID isn't a primary key on its own. Storing it in a globally unique column is wrong. The unique key is the pair, so in your own database:

UNIQUE (business_portfolio_id, business_scoped_user_id)

Kapso enforces the equivalent on the contacts it holds, so the identifiers you receive are already scoped correctly. The constraint above is for wherever you keep your own copy.

Cross-portfolio sends fail. Any business phone number owned by a portfolio can message a BSUID scoped to that portfolio. If you use a BSUID from a different portfolio, Meta rejects the request. If you run WhatsApp for several clients, each client's portfolio is its own world: their BSUIDs work with their numbers and with nothing else.

You can't deduplicate people across portfolios. Two BSUIDs belonging to the same person look like two unrelated identifiers. Meta scopes them that way deliberately, to stop businesses correlating users across portfolios they own separately.

Parent BSUIDs

There's one exception. A managed business with several portfolios can ask Meta to enrol them in a parent BSUID account, after which webhooks carry an extra parent_user_id that's stable across every enrolled portfolio:

US.ENT.11815799212886844830

Same format, with ENT inserted after the country code. A parent BSUID lets you reach the user from any phone number in any enrolled portfolio.

This is worth knowing about and, for most integrations, not worth acting on. It requires eligibility review through your Meta point of contact, it makes every enrolled portfolio visible to the others, and it doesn't merge contact books, which stay portfolio-scoped regardless. If you run one portfolio, ignore it. If you run several and share a CRM across them, it decides whether a customer is one record or one record per portfolio.

Where the portfolio comes from

To store a BSUID correctly you need to know which portfolio it belongs to at the moment the webhook arrives. That's a property of the connection the message came in on, not of the payload.

Kapso resolves that for you, so a BSUID reaches you already attached to the portfolio it belongs to. Your side is the part to get right: a BSUID stored against the wrong portfolio, or against none, is worse than one you didn't store, because it will match the wrong person later.