WhatsApp through Meta's Cloud API
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.
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, 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). See Keep your number on the WhatsApp Business app.
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:
- App settings, Basic: copy the App ID, and Show and copy the App secret.
- Business settings (business.facebook.com), Users, System users: add a system user (Admin), Add assets: your app and your WhatsApp account, with full control.
- On the system user, Generate new token for your app, with the permissions
whatsapp_business_messagingandwhatsapp_business_management(andbusiness_management). Choose Never for the expiry. - In your app, WhatsApp, Configuration, Webhook fields: subscribe
messages,smb_message_echoesandmessage_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:
- 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. - 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. - 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_appswithoverride_callback_uri), so you paste nothing into Meta's dashboard; - waits for Meta's check of that address (the
hub.challengehandshake): 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.
- subscribes your app to the WhatsApp account with Venom's own webhook address and a verify token it made
(
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.
- Send test to your own phone: Meta's
hello_worldtemplate 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 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_listandcomms_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_getfor the Support thread;comms_message_sendwithbody, atemplate, ormedia(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_sendmarks a conversation read;comms_template_listlists 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_managementandwhatsapp_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), once the deployment's operator has set up Venom's Meta app (operator's guide).
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.