2.3 Migration checklist

Every change this guide covered, roughly in dependency order, so each step is useful on its own even if you stop after it. The list assumes you hold the data and address the sends yourself; the section after it says which parts drop away when you don't.

Storage

• Add business_scoped_user_id, parent_business_scoped_user_id and username to your contact record.
• Record which business portfolio each contact belongs to. Without it you can't store a BSUID correctly.
• Make the phone number nullable, and drop any not-null or presence validation on it.
• Make the unique key (portfolio, bsuid), not bsuid alone.
• Widen the column to at least 135 characters. A parent BSUID is longer than you expect.

Inbound

• Read user_id and from_user_id from messages webhooks, and recipient_user_id from status webhooks.
• Stop assuming wa_id and from are present. They're omitted, not blank.
• Match on portfolio plus BSUID first, phone number second.
• Backfill now. Write the BSUID onto every contact that messages you today, while both identifiers still arrive.
• Subscribe to BSUID change notifications, and when one arrives merge onto the existing contact rather than inserting.
• Make that handler idempotent, since Meta redelivers webhooks.
• Repoint open conversations at the merged contact, not just the contact record.

Outbound

• Send to and recipient together where you have both, and remember the phone number wins.
• Validate BSUID format before sending, including the ENT parent variant.
• Handle error 131062 on one-tap, zero-tap and copy-code authentication templates.
• Apply the same treatment to the Calling API, and to Block Users, which uses user and user_id instead.

Downstream

• Update anything keyed on the phone number: CRM records, exports, deduplication, campaign audiences, analytics joins.
• Add a phone number request path where you need one, and a working branch for customers who decline.
• Decide whether to leave the Meta contact book enabled. Disabling it deletes what it holds, permanently.

Verification

• Take a real payload you've already received, delete wa_id and from, and replay it into your handler. That's the scenario that breaks integrations, and you don't need anyone's permission to test it.
• If you own the Meta app, the App Dashboard's webhook test tool sends all four scenarios directly. On Kapso's Meta app you won't have that dashboard, so replay is the route.
• Run a reconciliation pass over existing records to catch contacts the live path linked wrongly.

What Kapso already handles

If you're on Kapso, a good part of the list above is done on the data Kapso holds. You don't have to build any of this:

• The whole Storage section. Kapso stores all three identifiers, records the portfolio, and keys contacts on the portfolio-plus-BSUID pair.
• Matching an inbound message to the right contact, BSUID first.
• Applying a BSUID change to the contact and repointing its open conversations.
• Choosing between to and recipient, whenever you send by conversation or by contact rather than naming the identifier yourself.
• Showing the right thing in the inbox when there's no phone number, so agents aren't looking at a blank sender.

Which leaves a shorter list. These are yours whatever your provider does:

• Everything above, again, for any copy of the customer you keep outside Kapso. That's what chapters 1.1 and 1.2 are about.
• Use Kapso's contact id as the foreign key in that copy, not the phone number.
• The Outbound section, if you address sends yourself through the Meta proxy or by setting to.
• Authentication templates. No provider can send a one-tap or copy-code template to a BSUID.
• The Downstream section. Exports, deduplication, campaign audiences and analytics joins are yours, and they're where phone numbers are most often hardcoded.
• Asking for a phone number when you genuinely need one, and handling the customers who decline.

The short version: Kapso takes care of the WhatsApp side of identity. Your own database, and anything you export to, stays your problem.

One thing this guide didn't cover

Business usernames, meaning the username for your phone number rather than your customer's, are a separate task. They affect how customers find and recognise you, not whether your integration works. You can claim a reserved username now, and if the one you want already belongs to your Facebook Page or Instagram account you'll need to link the phone number first.

It's worth doing, and independent of everything above.

Separately, WhatsApp pricing changes on October 1, 2026, when the free-form replies you send inside the 24-hour window start being billed per message. The WhatsApp Pricing guide works out what that does to a bill.