--- title: 8.1 Connect to Meta (First Time) description: "Onboarding is a single-launch flow: one click opens Meta's own Embedded Signup dialog, which itself handles Business Portfolio selection, WABA/phone…" url: "https://peikly.com/docs/connect-to-meta-first-time/" updated: "2026-10-18" category: Meta Platform Connection tags: - Manual sync --- # 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](/docs/connect-the-number-you-already-use-in-the-whatsapp-business-app/)) 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](/docs/instagram-facebook-capabilities-channel-setup/)). ## 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: | Page / Action | Required Meta Permission | | --- | --- | | Phone Numbers, Chat, Campaigns | `whatsapp_business_messaging` | | Message Templates, Business Profile ([9.5](/docs/whatsapp-business-profile/)) | `whatsapp_business_management` | 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 | Message | Why It Happens | How to Fix | | --- | --- | --- | | `Unable to sync phone numbers from Meta.` | API error during sync | Retry from the Meta Platform Status page | | `No WhatsApp Cloud API phone numbers were discovered.` | No phones linked to the WABA | Add a phone number in Meta Business Manager first | | `Your WABA is connected but has no phone numbers yet.` | Phone not yet added to WABA | Add a phone in Meta Business Manager, then sync | | `Please sign in to Meta Platform first.` | You opened a WhatsApp page before connecting Meta at all | Complete [8.1 Connect to Meta](/docs/connect-to-meta-first-time/) | | `The required Meta permission '...' has not been granted. Please grant it from the Meta Platform Permissions page.` | The specific Meta permission a page needs (see Capability-Gated Pages) was never granted, or was later revoked | Click **Re-launch Meta** and approve that permission in Meta's dialog | | Popup blocked | Browser blocked the Meta Embedded Signup dialog | Allow popups for this site in browser settings | | The Meta window closed and the cards came back | You closed it, or Meta showed an error inside it | Choose again. If Meta's own message named a problem, Peikly explains it in plain words with one button to fix it | | Embedded Signup failed | Meta returned an error | Retry via **Re-launch Meta**; if persistent, check your Meta Business Manager account status | | A checklist item stays on "in progress" or fails | The background provisioning worker hit a transient Meta API error | Wait a few minutes and refresh; if it stays failed, click **Re-launch Meta** |