Meta WhatsApp and Facebook Leads portal setup runbook

Meta WhatsApp and Facebook Leads portal setup runbook gives implementation teams the exact Meta dashboard values, SquareOS destination fields, webhook subscriptions, token boundaries, and go-live evidence needed before WhatsApp or Meta lead capture is trusted in production.

What this page is for

Who should use it

Owner, implementation, communications admin, marketing admin, platform admin, support

Where to find it

Meta Developers, WhatsApp Manager, Business Settings, SquareOS Admin / WhatsApp Setting and Facebook Leads Setting

Before you start

Meta WhatsApp and Facebook Leads portal setup runbook: complete this runbook before a gym sends production WhatsApp templates or imports Meta lead ads through SquareOS.
Meta WhatsApp setup starts in Meta Developers / App Dashboard / WhatsApp / API Setup and records App ID, WhatsApp Business Account ID, Phone Number ID, display phone number, temporary test number state, and production phone readiness.
Meta system-user token setup uses Meta Business Settings / Users / System users, assigns the app and WhatsApp Business Account assets, grants whatsapp_business_management and whatsapp_business_messaging where approved, and stores only a masked credential reference in SquareOS.
Meta WhatsApp webhook setup uses Meta Developers / App Dashboard / Webhooks or WhatsApp Configuration with SquareOS callback URL GET/POST /engagement/meta-whatsapp/webhook, verify token, messages subscription, statuses subscription, and x-hub-signature-256 app-secret validation.
Meta WhatsApp template setup records template name, language, category, body/header/footer/buttons, variable order, approval status, rejection reason, and external template id before SquareOS Sync templates.
SquareOS WhatsApp fields map Meta values to Channel Account channel WHATSAPP, provider Meta WhatsApp, account name, externalAccountId as WABA/phone reference, configJson phoneNumberId/displayPhoneNumber/appId, credentialsJson secret reference, webhook verify token, sender account senderValue, and template externalTemplateId.
Facebook Leads setup starts in Meta Developers / App Dashboard / Webhooks and Page subscriptions, subscribes leadgen, records Page ID, Form ID, App ID, App Secret, Page or system-user token, ad account/campaign/ad ids when available, and Lead Ads Testing Tool result.
Facebook Leads permissions and token proof must include pages_manage_ads, pages_read_engagement, leads_retrieval, business/app asset ownership, and Page/Form access for the exact gym Page.
SquareOS Facebook Leads fields map Meta values to Channel Account channel FACEBOOK_LEADS, provider Facebook Leads, externalAccountId Page/Form/App reference, credentialsJson token reference, configJson form mappings/source/channel/owner/duplicate policy, webhook verify token, and lead testing evidence id.
Meta go-live proof requires one opted-in WhatsApp template send with signed status callback and inbound reply, plus one Meta Lead Ads test lead that creates or matches one person, opportunity, task, facebookLeadEvent, and crm.facebook_lead.created.v1 outbox event.

Daily workflow

Confirm the Meta Business portfolio and production app first. The app, WABA, phone number, Page, form, ad account, and system user must belong to the same client or an explicitly approved partner-managed setup.
Open Meta Developers, choose the production app, then open WhatsApp / API Setup. Copy the App ID from app settings, WhatsApp Business Account ID, Phone Number ID, and display phone number. Record whether the phone is still a temporary test number or an approved production business phone.
Open Meta Business Settings / Users / System users. Create or select the implementation system user, assign the production app and WhatsApp Business Account assets, grant approved WhatsApp permissions, generate the token, and store only the SquareOS credential reference or masked token reference in the extraction row.
Open Meta Developers / App Dashboard / Webhooks or WhatsApp Configuration. Enter the SquareOS callback URL for GET and POST /engagement/meta-whatsapp/webhook, paste the SquareOS verify token, subscribe to messages and statuses, and confirm SquareOS records webhookStatus VERIFIED after the challenge.
Open WhatsApp Manager / Message templates. For every SquareOS template, capture template name, language, category, body/header/footer/buttons, variable order, approval status, rejection reason if any, and external template id. In SquareOS, Sync templates only after the Meta template is approved or explicitly marked pending for a launch limitation.
In SquareOS Admin / WhatsApp Setting or Channel Account, create the Meta WhatsApp account with channel WHATSAPP, provider Meta WhatsApp, account name, externalAccountId as WABA plus phone reference, configJson containing phoneNumberId, displayPhoneNumber, appId, WABA, and webhook metadata, and credentialsJson containing only secret references.
Create a SquareOS sender account for the approved WhatsApp display phone or phone-number reference. A sender must be connected to the Meta WhatsApp channel account before Inbox, profile activity, campaign, or automation sends can be enabled.
For Facebook Leads, open Meta Developers / App Dashboard / Webhooks. Subscribe the Page object to leadgen, then confirm the Page and form in Business/Page settings. Copy Page ID, Form ID, App ID, App Secret reference, Page or system-user token reference, and ad account/campaign/ad ids where available.
Confirm Meta permissions before import testing: pages_manage_ads, pages_read_engagement, leads_retrieval, business/app asset ownership, and Page/Form access for the exact gym Page. Missing permission is a setup blocker, not a SquareOS duplicate-handling issue.
In SquareOS Admin / Facebook Leads Setting or Channel Account, create provider Facebook Leads with channel FACEBOOK_LEADS, externalAccountId as Page/Form/App reference, credentialsJson token reference, configJson form mappings, source/channel mapping, owner mapping, duplicate policy, and webhook verify token.
Use the Meta Lead Ads Testing Tool or one real test form submission. The pass condition is a verified signed webhook, Graph lead fetch, duplicate-safe person create or match, opportunity/task creation according to mapping, facebookLeadEvent record, and crm.facebook_lead.created.v1 outbox event.
Record official source references used for the extraction row: Meta WhatsApp Cloud API setup, WhatsApp webhooks, WhatsApp templates, Lead Ads webhooks, and Lead Ads testing tool documentation. If Meta changes portal labels, keep the SquareOS field mapping and update the attempted portal path in the evidence row.

Watch out

Do not paste Meta app secret, system-user access token, Page token, webhook verify token, or raw webhook payload into screenshots, support tickets, launch trackers, mobile screens, or analytics events.
Do not confuse display phone number with Phone Number ID. SquareOS sends to Meta using the phone number id/account configuration, while staff may recognize the display number.
Do not create WhatsApp templates in SquareOS without a connected Meta WhatsApp provider account; the backend rejects WhatsApp templates until the provider account is connected.
Do not mark free-form WhatsApp sends live-ready unless the backend has an active service-window rule. Normal outbound campaign and automation sends should use approved templates.
Do not certify one Page/form, one WABA, or one phone number and assume another branch or campaign is covered. Each production identity needs its own extraction row and go-live evidence.
Do not import Meta leads directly from a CSV when the webhook/Graph path is broken unless the owner accepts it as a temporary manual fallback and support records the follow-up issue.

Use the left menu to open related pages in Start Here.
Use Ask Docs for questions that are already covered in this public documentation.