Skip to content
Docs menu

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.

View .md

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:

  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.

  1. 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 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), 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.