Skip to content
Docs menu

Set up "Connect with Meta" for WhatsApp

Everything the operator does in Meta's developer console so Settings, Comms offers Connect with Meta (WhatsApp Embedded Signup and coexistence): the app, Tech Provider, app review, the login configuration, domains, the webhook and four environment variables.

View .md

Connect with Meta is WhatsApp's Embedded Signup run through your deployment's own Meta app: an org admin signs in to Facebook in Meta's window, picks their business and number, and Venom sets up the rest. It is the only way Meta offers to connect a number that stays on the WhatsApp Business app (coexistence).

The button appears in Settings, Comms only when the deployment has Venom's Meta app configured (the variables at the end). Without them, orgs connect with their own Meta app (WhatsApp through Meta's Cloud API), and nothing below is needed. Nothing calls Meta, and no Meta script loads, until an admin uses it.

Each step says which Meta page it comes from (under developers.facebook.com/documentation/business-messaging/whatsapp/ unless another address is given), as read on 2026-11-19. Steps marked unverified are not on a Meta page we could read; check them in the dashboard.

1. The Meta app

  1. A business portfolio (business.facebook.com) for the company that operates this deployment.
  2. developers.facebook.com, Create app, type Business, linked to that portfolio. Add the WhatsApp use case and Facebook Login for Business (embedded-signup/implementation).
  3. App settings, Basic: note the App ID and the App secret; add a privacy policy URL, an app icon and a category (solution-providers/get-started-for-tech-providers: needed for app review).
  4. Optional, recommended: App settings, Advanced, Security, Require App Secret. Venom sends appsecret_proof with every call made with a token (Graph API "Securing requests", developers.facebook.com/docs/graph-api/securing-requests).

2. Become a Tech Provider

From solution-providers/get-started-for-tech-providers:

  1. In the app's dashboard: Use cases, Customize, Tech Provider onboarding.
  2. Business verification of the portfolio: "Your business must be verified before you can start the app review process."
  3. App review for advanced access to whatsapp_business_messaging and whatsapp_business_management (solution-providers/app-review). For each permission Meta asks for a written description and a screen recording ("Both written descriptions and screen recordings are required for each permission", "You must submit a different video clip for each permission", no screenshots):
    • whatsapp_business_messaging: explain what messaging your app offers; video: "your app being used to send a message to a WhatsApp number, and the WhatsApp client (either web or mobile app) receiving and displaying the sent message". Record Venom's Support inbox sending a reply that arrives on a phone.
    • whatsapp_business_management: explain how you use it on the accounts of clients you onboard; video: "your app being used to create a message template". Meta accepts "your app, or WhatsApp Manager" for creating the template.
    • Meta says review takes "about 24 hours", and: "Make sure your test users have a developer or admin role in the Meta app being used to implement Embedded Signup."
    • Without advanced access, calls on accounts your business does not own "return error code 200".
  4. If you are a Solution Partner instead, Meta also requires a line of credit (embedded-signup/implementation).

Only for your own number: "if you are using the API for yourself as a Direct Developer, you do not need Advanced access or app review" (solution-providers/app-review). Coexistence is not covered by that: Meta's Onboard WhatsApp Business app users page requires "You must already be a Solution Partner or Tech Provider." A deployment that is only a Direct Developer can connect new numbers with Connect with Meta, but a number that stays on the WhatsApp Business app needs the Tech Provider steps above first.

3. Facebook Login for Business

From embedded-signup/implementation and embedded-signup/version-4, and developers.facebook.com/documentation/facebook-login/facebook-login-for-business:

  1. Facebook Login for Business, Settings, Client OAuth settings, set to Yes: Client OAuth login, Web OAuth login, Enforce HTTPS, Embedded Browser OAuth Login, Use Strict Mode for redirect URIs, Login with the JavaScript SDK.
  2. Allowed domains for the JavaScript SDK and Valid OAuth redirect URIs: your cloud's origin, e.g. https://cloud.example.com (the page that opens the popup is https://cloud.example.com/comms/meta-signup). "Only domains that have enabled HTTPS are supported", and Meta returns the ids and the code "only if the domain of the page that spawned the flow is listed".
  3. Configurations, Create from template: "WhatsApp Embedded Signup Configuration With 60 Expiration Token", or a custom configuration with the WhatsApp Embedded Signup login variation. Choose Cloud API: in v4 and v5 that selects the WhatsApp account and messaging account assets and the whatsapp_business_management and whatsapp_business_messaging permissions. Token type: system-user access token (a business token). Expiry: Meta's template name says 60 days; the Facebook Login for Business page says these tokens default "to never expire" (whether a custom configuration's screen offers the choice is unverified). Meta documents no refresh for them: with 60 days, admins connect again before the token expires (the status panel shows the date).
  4. Note the Configuration ID.

Venom launches Embedded Signup v5 (embedded-signup/versions: v2 and v3 were deprecated on 2026-10-15 and are served as v4; v5 was released 2026-10-20 and turns WhatsApp Business app onboarding on by default).

4. The app's webhook

From webhooks/create-webhook-endpoint, webhooks/override and embedded-signup/onboarding-business-app-users:

  1. In the app: WhatsApp, Configuration, Webhook, Edit. Callback URL https://<your cloud>/api/integrations/comms/meta-app; Verify token: the value of VENOM_META_VERIFY_TOKEN (any long random string you choose). Meta checks it at once.
  2. Webhook fields: subscribe account_update (required for Embedded Signup), messages, history, smb_app_state_sync, smb_message_echoes and message_template_status_update.

Venom points each connected account's own events (messages, statuses, echoes, history, contacts) at a per-number URL of its own with subscribed_apps and override_callback_uri, so they never mix between organisations. Meta never sends account_update or template states to that override: they come to the app's callback above, where Venom routes them by account to the numbers connected through this app only.

5. The deployment's environment

Set these in the cloud's environment (Vercel: Project, Settings, Environment Variables, Production; self-hosted: the cloud's .env), then redeploy:

Variable Value
VENOM_META_APP_ID the App ID (step 1)
VENOM_META_APP_SECRET the App secret (step 1). Server only: it exchanges codes, signs appsecret_proof and checks webhook signatures; it is never sent to a browser or stored per org
VENOM_META_CONFIG_ID the Configuration ID (step 3)
VENOM_META_VERIFY_TOKEN the verify token you typed in step 4

With the first three set, Settings, Comms shows Connect with Meta; the fourth makes the app webhook answer Meta's check. VENOM_VAULT_KEYS must be set (the business tokens are sealed in the vault).

What the browser loads

Only on /comms/meta-signup, and only after the admin presses Load Meta's sign-in (the page says first that the browser will contact Meta), the browser loads https://connect.facebook.net/en_US/sdk.js (the address on Meta's embedded-signup/implementation page) and Meta's popup runs on facebook.com. That page alone has a Content Security Policy that allows connect.facebook.net, frames on facebook.com and calls to graph.facebook.com; no other page of the app allows any Meta host. Meta publishes no CSP list for its SDK, so the hosts are those the SDK is known to use (unverified beyond the script URL). Venom turns the SDK's automatic app-event logging off.

The server then calls graph.facebook.com only: the code exchange (GET /oauth/access_token, which Meta's embedded-signup/onboarding-customers-as-a-tech-provider page shows without a redirect_uri), debug_token, and the same setup calls as an org's own app.

Checking it

  • Settings, Comms shows Connect with Meta beside Use your own Meta app.
  • A wrong VENOM_META_VERIFY_TOKEN makes Meta refuse the callback in step 4.
  • Embedded Signup's errors appear in the page in Meta's own words (session logging), e.g. "This feature is unavailable for phone numbers from this region" (3441042, embedded-signup/errors).

For tests and local walk-throughs only, META_SDK_URL swaps Meta's script for a fake on loopback (ignored on Vercel), and META_GRAPH_BASE does the same for the Graph API. Leave both unset in a real deployment.

See also: Coexistence, WhatsApp through Meta's Cloud API.