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.
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
- A business portfolio (business.facebook.com) for the company that operates this deployment.
- developers.facebook.com, Create app, type Business, linked to that portfolio. Add the WhatsApp use case and Facebook Login for Business (embedded-signup/implementation).
- 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).
- Optional, recommended: App settings, Advanced, Security, Require App Secret. Venom sends
appsecret_proofwith 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:
- In the app's dashboard: Use cases, Customize, Tech Provider onboarding.
- Business verification of the portfolio: "Your business must be verified before you can start the app review process."
- App review for advanced access to
whatsapp_business_messagingandwhatsapp_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
developeroradminrole 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".
- 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:
- 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.
- 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 ishttps://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". - 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_managementandwhatsapp_business_messagingpermissions. 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). - 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:
- In the app: WhatsApp, Configuration, Webhook, Edit. Callback URL
https://<your cloud>/api/integrations/comms/meta-app; Verify token: the value ofVENOM_META_VERIFY_TOKEN(any long random string you choose). Meta checks it at once. - Webhook fields: subscribe
account_update(required for Embedded Signup),messages,history,smb_app_state_sync,smb_message_echoesandmessage_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_TOKENmakes 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.