---
title: Set up "Connect with Meta" for WhatsApp
description: "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."
section: deploy
order: 52
audience: [operator]
sources: [services/nodejs-cloud/lib/comms/meta-signup.ts, services/nodejs-cloud/lib/comms/meta-csp.ts, services/nodejs-cloud/app/api/integrations/comms/meta-app/route.ts, "services/nodejs-cloud/app/(console)/comms/meta-signup/page.tsx", docs/adr/0061-venom-comms.md]
features: []
---

**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](/docs/comms/whatsapp-coexistence.md)).

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](/docs/comms/whatsapp-meta.md)),
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](/docs/comms/whatsapp-coexistence.md), [WhatsApp through Meta's Cloud API](/docs/comms/whatsapp-meta.md).
