Skip to main content

​
Connect an Additional WABA

Your first WABA covers one sender. This guide covers the multi-brand, multi-region case: adding a second (or third) WhatsApp Business Account to the same Orbit organization so each sender runs its own templates, limits, and quality rating without cross-contaminating the others.

​
When to add a second WABA

Add another WABA when the senders are genuinely different businesses in Meta’s eyes:
  • Multi-brand — you operate two consumer brands (or a parent + a DBA) and each needs its own display name, profile, and templates. One WABA can only carry one display name at a time; a second brand on the same WABA fails Meta’s display-name review.
  • Multi-region — a number per market (e.g. one UK sender, one UAE sender). Each WABA bills directly to its own Meta Business Manager, so per-region finance teams can attach their own payment method.
  • Customer care vs. transactional — separating a support inbox from order notifications keeps the marketing-quality score of one lane from dragging the other’s messaging tier down.
  • Agency / white-label — you run WhatsApp for several end clients; each client’s WABA stays its own legal entity, and Orbit holds them side by side.
If the senders are the same brand and the same Business Manager, prefer a second phone number on the existing WABA instead — it costs less review time. Add a whole new WABA only when the entity, brand, or billing boundary actually differs.

​
The two onboarding lanes

The dedicated connect page — Settings → Channels → WhatsApp → Connect another WABA (route /settings/channels/whatsapp/add-waba) — presents the two Meta Embedded Signup variants side by side. Pick by what already exists: Coexistence is gated by Meta per account and region — if the option is not offered for your account, fall back to the Cloud API lane. Coexistence keeps the phone usable for ad-hoc replies; Cloud API gives you the full server-side feature set.

​
Walkthrough — Embedded Signup (Cloud API)

  1. Open Settings → Channels → WhatsApp and click Connect another WABA. The waba-picker on the WhatsApp workspace page (/messages/whatsapp) deep-links to the same route.
  2. The page lists your already-connected accounts at the top, so you can confirm the new one is not a duplicate.
  3. On the Cloud API card, click Connect with Facebook. Meta’s OAuth dialog opens in a popup.
  4. Sign in with the Facebook account that is an admin on the Business Manager that will own the new WABA.
  5. Pick the Business Manager, then Create a new WABA — do not reuse an existing WABA unless you are porting (see the migration guide).
  6. Add + verify the new phone number (SMS or voice code — outside the US, pick Phone call; the SMS path is frequently filtered).
  7. Choose the display name and upload the square (≥ 640×640) profile photo when the wizard asks. The display name re-enters Meta review if changed later, so match your documents here.
  8. The popup closes on a stable, bookmarkable URL — the route at /settings/channels/whatsapp/add-waba exists specifically so this redirect target never depends on a modal’s internal state — and Orbit lands you on the WhatsApp workspace (/messages/whatsapp) with the new account selected in the picker.

​
Walkthrough — Coexistence (WhatsApp Business App)

  1. Same entry point — Settings → Channels → WhatsApp → Connect another WABA.
  2. On the Coexistence (keep Business App) card, click Connect with Facebook.
  3. Sign in with a Facebook account that administers the Business Manager tied to the phone-based account.
  4. Select the existing WABA the Business App runs on (Coexistence links the account; it never creates a new one).
  5. Confirm the phone number of the handset account. Meta links the Business App to Cloud API as a coexisting pair.
  6. From this point the handset keeps working: messages sent from the phone mirror into the dashboard inbox, and the dashboard can send via templates and the API using the same number.
If Meta rejects the Coexistence pairing with an eligibility error, the account or region is not gated in — retry on the Cloud API lane.

​
After the connection lands

The new WABA appears in two places:
  • The WABA picker at Messages → WhatsApp (/messages/whatsapp) — the picker auto-selects the most recently connected account after the redirect back. Every surface in the workspace (inbox, templates, analytics) follows the selected WABA.
  • Settings → Channels → WhatsApp — the connection card list, where the new sender shows its health, messaging-tier, and quality tiles.
Scope the following to the new WABA explicitly:
  1. Templates — submit new templates while the new WABA is selected in the picker (/messages/templates). Templates belong to one WABA; they are not shared across accounts.
  2. Senders — any campaign, flow, or API call that sends WhatsApp should pin the WABA/number in its configuration as well, so traffic never leaks through the default account.
  3. Analytics — the Analytics “Messaging Limit” and quality views filter by the picker selection, so verify the new sender’s tier and rating appear before you route traffic.

​
Who can connect — RBAC

The route is owner/admin-only, on the same tier as the Settings → Channels parent guard. An operator with a lower role lands on the connect page’s guard and sees the request routed to an owner/admin. This is deliberate: linking a WABA binds the organization to a Meta Business Manager and creates a billing-visible association on Meta’s side. The credentials themselves are stored encrypted; the role gate protects the linkage operation, not the secret.

​
Why a route, not a modal — reload safety

Meta Embedded Signup is a window.open OAuth popup that redirects back to Orbit. A modal dialog loses that redirect when the operator reloads mid-flow; a dedicated route survives it. Concretely:
  • The redirect-back lands on a stable URL you can bookmark or share with a teammate.
  • A page refresh mid-flow re-renders the same connect surface instead of a closed modal over a workspace page.
  • The guard can wrap the whole page, so there is no in-page component-level check to bypass.
If you find the popup closes without returning (common on Safari or corporate SSO), reopen the route and re-trigger — Meta preserves partial state server-side.