8.1 Connect to Meta (First Time)

Onboarding is a single-launch flow: one click opens Meta’s own Embedded Signup dialog, which itself handles Business Portfolio selection, WABA/phone selection, and permission grants. There is no separate "select WABA" or "select phone" screen inside Application — Meta’s dialog is where that happens.

Step-by-Step Instructions #

1. Click the plug icon (Connections) in the top bar, then choose WhatsApp, Instagram, or Facebook. You can also pick Manage all connections and open the Meta card there. (Meta Platform no longer has its own entry in the sidebar; WhatsApp and Social Media menus appear in the sidebar once Meta is connected.)
2. The onboarding page shows readiness tiles for WhatsApp, Instagram, and Facebook (Instagram/Facebook tiles only appear when those modules are enabled for your plan).
3. For WhatsApp, first choose the kind of number: Use my current WhatsApp Business number (you keep your number and your app, see 9.9) or Use a new number. Then click Open the Meta window. This opens the Meta Embedded Signup dialog via the Facebook SDK — not a generic popup window. (For Instagram or Facebook, use the equivalent action on its tile.) If Meta is not connected yet, the Just need WhatsApp? block at the top connects your Meta account and your number in one go.
4. Sign in to your Facebook/Meta account when prompted.
5. Inside Meta’s dialog: select or create a Meta Business Portfolio, select your WhatsApp Business Account (WABA) and phone number (or register a new one, or connect the account of your WhatsApp Business app), and grant the requested permissions.
6. Complete and close Meta’s dialog.
7. Application shows a live capability checklist that polls status while the connection is provisioned in the background — each item (permission verification, webhook subscription, WABA/phone discovery, template sync, and similar steps) updates from pending to in-progress to done (or failed) without a page reload.
8. Once every checklist item completes, the tile shows Connected and the WhatsApp sidebar menu unlocks.

If Setup Is Interrupted or a Step Fails #

• The onboarding session is remembered (it is not lost if you close the tab or a step fails partway).
• Click Re-launch Meta on the onboarding page to resume — you do not need to restart the whole flow or re-grant permissions that already succeeded.
• If a specific checklist step keeps failing, it usually means the granted Meta permissions don’t cover that step; re-launch and make sure every requested permission is approved in Meta’s dialog.
• The initial connection requests every permission the CRM can use, so one trip through Meta’s dialog is normally enough. If you declined something, Grant all missing permissions on the Channel setup page re-asks for exactly what is still missing (see 8.3a).

What Happens After #

• A MetaPlatformConnection record is created for your tenant.
• Connected WhatsApp Business Accounts and phone numbers are discovered and stored.
• WhatsApp features become available in the sidebar — but only the specific pages whose required Meta permission was actually granted (see Capability-Gated Pages below).
• Template downloads begin automatically.

Capability-Gated Pages #

Application never shows a control for a Meta action your connection isn’t actually authorized to call. Each WhatsApp-related controller checks for a specific granted permission before rendering:

If a permission is missing when you open a gated page, you’re redirected with an explanatory message rather than seeing a broken screen (see the Errors table below). Re-launching Meta onboarding and approving the missing permission in Meta’s dialog resolves it.

Errors, Messages, and Exceptions #