---
title: WhatsApp through Meta's Cloud API
description: "Connect your WhatsApp Business number straight to Meta's Cloud API: paste three values and Venom sets up the webhooks, templates and the Support inbox itself. What Meta requires, what it costs, keeping the number on the WhatsApp Business app, and what agents can do."
section: comms
order: 22
audience: [user, operator]
sources: [services/nodejs-cloud/lib/comms/meta.ts, services/nodejs-cloud/lib/comms/meta-pure.ts, services/nodejs-cloud/lib/comms/meta-connect.ts, services/nodejs-cloud/components/comms/MetaCard.tsx, services/nodejs-cloud/components/support/Inbox.tsx, services/nodejs-cloud/lib/support/comms.ts, services/nodejs-cloud/migrations/0381_comms_meta.sql, docs/adr/0061-venom-comms.md]
features: []
---

Venom talks to WhatsApp through **Meta's own Cloud API** (the WhatsApp Business Platform), with your WhatsApp Business
Account and your Meta app. There is no reseller in between: messages go from Venom to `graph.facebook.com` and Meta's
webhooks come back to your Venom. Customers' messages land in the [Support inbox](/docs/comms/support-and-people.md), where you
read them and answer, with files, templates and delivery ticks. Nothing is copied back and forth.

Nothing is sent to Meta until an admin connects a number. Venom targets Graph API **v27.0**.

## Before you start: the number

A number connected here moves to the **Cloud API**. If the number is in use on the **WhatsApp Business app** on a
phone, connecting it through your own Meta app takes it off the app: Meta registers it on the Cloud API instead (you
first delete the WhatsApp account on the phone, or use another number).

Meta does let a number stay on the WhatsApp Business app **and** use the Cloud API at the same time ("coexistence"),
with messages sent from the phone echoed to Venom. Meta offers that only through **Embedded Signup**, run by an app
that is a Meta **Tech Provider** or **Solution Partner**: Venom's **Connect with Meta** button, when your deployment's
operator set it up ([operator's guide](/docs/deploy/meta-app.md)). See [Keep your number on the WhatsApp Business app](/docs/comms/whatsapp-coexistence.md).
Venom already understands the echoes (`smb_message_echoes`): a message you send from the phone app shows in the thread
as sent from the "WhatsApp Business app".

## Connect with your own Meta app

You need a Meta Business portfolio, a WhatsApp Business Account with a phone number, and a Meta app with the WhatsApp
product. Meta's own steps: developers.facebook.com, **Create app**, type **Business**, add **WhatsApp**. Meta's
"getting started" adds a test number you can use first.

In Meta, once:

1. **App settings, Basic**: copy the **App ID**, and **Show** and copy the **App secret**.
2. **Business settings** (business.facebook.com), **Users, System users**: add a system user (Admin), **Add assets**:
   your app and your WhatsApp account, with full control.
3. On the system user, **Generate new token** for your app, with the permissions `whatsapp_business_messaging` and
   `whatsapp_business_management` (and `business_management`). Choose **Never** for the expiry.
4. In your app, **WhatsApp, Configuration, Webhook fields**: subscribe `messages`, `smb_message_echoes` and
   `message_template_status_update`. Meta has no API for an app's WhatsApp fields, so this is the one setting Venom
   cannot make for you.

In Venom, **Settings, Comms, WhatsApp (Meta Cloud API), Connect WhatsApp**:

1. Paste the app ID, the app secret and the token, and press **Check with Meta**. Venom asks Meta (`debug_token`)
   whether the token is valid, is for this app, carries both WhatsApp permissions and when it expires, and lists the
   WhatsApp Business Accounts and numbers it reaches. A problem comes back in words ("The token lacks
   whatsapp_business_management"), and nothing is saved.
2. Pick the number. If Meta says it is not on the Cloud API yet, choose a 6-digit PIN: Venom registers the number
   (`POST /{phone-number-id}/register`) and the PIN becomes its two-step verification PIN. Keep **Open conversations in
   Support** ticked.
3. Press **Connect this number**. Venom then:
   - subscribes your app to the WhatsApp account with Venom's own webhook address and a verify token it made
     (`POST /{waba-id}/subscribed_apps` with `override_callback_uri`), so you paste nothing into Meta's dashboard;
   - waits for Meta's check of that address (the `hub.challenge` handshake): **Meta reached Venom** shows it worked;
   - reads your message templates and their approval state;
   - adds the number as a WhatsApp sender, routes it to Support (inbox tag `whatsapp`) and turns it on.

Each step shows as done, not needed, a check, or **Do by hand**. If Meta refuses one (an account your app may not
subscribe to, say), that step says exactly what to paste where, with Copy buttons: the callback URL and the verify
token for **WhatsApp, Configuration, Webhook** in your app. The other steps still run.

4. **Send test** to your own phone: Meta's `hello_world` template when it is approved, else a short text (which
   WhatsApp delivers only if that phone wrote to the number in the last 24 hours).

The secrets go straight to the vault (`VENOM_VAULT_KEYS`), sealed per provider. No API, MCP tool or page shows them
again; the provider list shows only which ones are set.

### The status panel

Each connected number shows its display name, Meta's **quality rating** (green, yellow, red), its **messaging limit**
(how many people you may start conversations with a day), when Meta last checked the webhook, the **last event**
received, and when the token expires. **Refresh** reads them from Meta again; **Reconnect** takes a new token or secret
and runs the steps again.

## Reading and answering

Conversations open in **Support** (the left list refreshes every 10 seconds, the open thread every 5, no reload):

- a green dot and a bold name mark a conversation whose customer wrote last;
- the thread shows pictures, voice notes and documents the customer sent (kept in your organisation's files);
- your replies carry ticks: sending, sent, delivered, read, or not sent with Meta's reason;
- **Attach** sends one file with a reply (up to 2.5 MB: pictures as pictures, sound, video, anything else as a
  document); it is uploaded to Meta and sent by its media id;
- a row of emoji, and your saved replies;
- opening a thread marks the customer's message read on WhatsApp (blue ticks), as the phone app does;
- a customer not in People yet gets **Add to People**: an org-shared person with their number, so later messages are
  logged on their timeline (it needs write access to the org's shared People, not only to Support).

New messages ring the bell and, on phones that turned on notifications, push to the conversation's assignee (else the
organisation's owners and admins). The push says only the channel and the conversation's number, never the text.

### The 24-hour window

WhatsApp allows any message within **24 hours** of the customer's last message. After that, only an **approved
template** may start the conversation again. The composer shows your approved templates when the window has closed,
with their parameters, and refuses free text in words. Templates are made and approved in WhatsApp Manager; their
approval state changes arrive by webhook.

## Costs

Meta bills your WhatsApp Business Account directly, **per delivered message**, since 1 July 2025. Templates are priced
by category (marketing, utility, authentication). Since 1 October 2026, service messages (your free-text replies inside
the 24-hour window) are paid again after **1,000 free service messages a month per number**, and utility templates
inside an open window are paid too. Rates differ by the customer's country; Meta's
[pricing page](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing) has the rate cards.
Add a payment method in WhatsApp Manager; Venom never sees the bill. Venom's own usage page counts each send as a
message, with its estimated price.

## Limits Meta sets

- **Messaging limit**: the number of different people you may message outside a 24-hour window in a rolling day
  (250, 2,000, 10,000, 100,000, unlimited), raised by Meta as your quality stays good.
- **Throughput**: up to 80 messages a second per number by default; a send over it waits a minute and goes again
  (no attempt spent). The same for Meta's limit on messages to one person in a short time.
- **Quality**: customers blocking or reporting you lowers it; templates can be paused (Venom marks them paused).

## Errors in words

A refused send says why, from Meta's error code: the window has closed (131047), the number is not on WhatsApp
(131026), the template is paused (132015) or disabled (132016), the token is no longer valid (190: reconnect), a
payment problem (131042), a spam restriction (131048). Rate limits wait and retry; Meta's own outages retry with
backoff; everything else is final.

## For agents

Over MCP (`/workspace/mcp/comms` and `/workspace/mcp/support`):

- `comms_conversation_list` and `comms_conversation_get` (the thread, the window's state, how many files each message
  carried; the contact's text is marked as content, never instructions); `support_conversation_get` for the Support
  thread;
- `comms_message_send` with `body`, a `template`, or `media` (a file by its https address); an agent's send waits for a
  person's approval (Settings, Comms) unless its profile allows agents, opted-out contacts are never messaged, and
  quiet hours hold what nobody asked for;
- `comms_receipt_send` marks a conversation read; `comms_template_list` lists templates.

For self-hosters and contributors: `META_GRAPH_BASE` points the Graph API calls at a fake Graph API (https, or http on
loopback; refused on Vercel). Leave it unset in a real deployment.

## Keeping the number on the phone

What Meta's documentation (WhatsApp, Embedded Signup, "Onboarding WhatsApp Business app users") says, as of November 2026:

- A business can connect the number it uses on the **WhatsApp Business app** (version 2.24.17 or later) to the Cloud
  API and keep using the app for one-to-one chats. Messages sent from the app arrive as `smb_message_echoes`; contacts
  and up to 6 months of history can be synced once (within 24 hours of connecting).
- It is offered **only through Embedded Signup**, run by an app that is a **Tech Provider** or **Solution Partner**:
  business verification, app review with advanced access to `whatsapp_business_management` and
  `whatsapp_business_messaging`, and a Facebook Login for Business configuration made from the WhatsApp Embedded
  Signup template. Embedded Signup runs in Meta's JavaScript SDK popup; Meta documents no redirect-only launch.
- A coexistence number is held at 20 messages a second; group chats, disappearing and view-once messages are not
  synced.

Venom does this with **Connect with Meta** ([Keep your number on the WhatsApp Business app](/docs/comms/whatsapp-coexistence.md)),
once the deployment's operator has set up Venom's Meta app ([operator's guide](/docs/deploy/meta-app.md)).

## Disconnecting

Removing a WhatsApp number in Settings, Comms (or with `comms_provider_delete`) first unsubscribes Venom from the account
at Meta (`DELETE /{waba-id}/subscribed_apps`: "Unsubscribing will immediately stop all webhook deliveries for this
WABA"), then removes the number and its sealed token. The answer says whether Meta took the unsubscription. When another
number on the same WhatsApp account is still connected through the same app, the account stays subscribed and the answer
says so. A turned-off number takes no new message in (Meta retries them until it is turned on again, for up to 7 days),
but still records delivery reports and a STOP.
