WhatsApp Cloud API
Connect sends and receives WhatsApp through Meta's WhatsApp Business Platform, using the Cloud API on the Graph API. Inside a customer's 24-hour window it sends free text. Outside it, only an approved template. Inbound messages, voice notes and delivery statuses arrive as signed webhooks, and WhatsApp calls are answered by the same realtime voice engine as phone calls.
What it is#
The WhatsApp Business Platform is Meta's API for businesses. The Cloud API is the version Meta hosts: a business registers a phone number, Meta stores and relays the messages, and the business calls graph.facebook.com and receives webhooks.
Its rules shape the product. A business may reply freely for 24 hours after a customer's message. Outside that window it may send only a pre-approved template, and Meta prices conversations by category.
- Category
- Messaging API
- Endpoint
- Graph API
v21.0(in the code at this commit) - Modules
backend/app/whatsapp.py,whatsapp_calling.py,whatsapp_engine.py,comms_providers.py- Official site
- developers.facebook.com/docs/whatsapp
Where Connect uses it#
| Place in Connect | What it does there |
|---|---|
whatsapp.py | Sending text and templates, media, and reading webhooks |
whatsapp_engine.py | Replies: deterministic button and list answers skip the model |
whatsapp_calling.py | WhatsApp voice calls into the realtime engine |
omni_journey.py | A prospect's WhatsApp journey, joined to a person only by a signed link |
How it connects#
- A customer writes; Meta posts a signed webhook
- Connect verifies the signature, then records the message once
- The reply is decided under the workspace's autonomy rules
- Inside the 24-hour window, text; outside, an approved template
- Status webhooks (sent, delivered, read) update the message
Benefits and limits#
What it gives Connect:
- Reach on the channel many customers in India prefer.
- Templates make re-engagement possible, within Meta's rules.
- Status webhooks give per-message evidence of delivery (message status).
Where it stops, and what Connect does about it:
- Free text outside the 24-hour window is refused by Meta. Connect does not try to bypass it.
- Templates need Meta's approval, which takes time and can be rejected.
- 'Read' depends on the recipient's privacy settings, so its absence proves nothing.
Security and privacy#
- Webhooks are verified before use. Content in a message is data, never an instruction.
- Access tokens are stored encrypted, and the Owner's token is kept apart from each business's own.
- A STOP or opt-out is honoured across channels (opt-out keywords).
Licence, cost and versions#
| Question | Answer |
|---|---|
| Licence | Commercial service under Meta's WhatsApp Business terms |
| Cost | Per Meta's pricing, by message category and country |
| Version | Graph API v21.0 in the code. Meta retires Graph versions on a published schedule |
| Compatibility | Cloud API, not the retired on-premises API |
Troubleshooting#
- A reply is refused outside the window
- Use an approved template, or wait for the customer to write again.
- Webhooks stop arriving
- The app's webhook subscription or verify token changed in Meta's dashboard. See the inbound webhook.
- Template rejected
- Meta's review reason is returned. Marketing wording in a utility template is a common cause.
Official references#
Questions#
Does Connect use an unofficial WhatsApp client?
No. Only Meta's official Business Platform API, with the business's own registered number and consent.
Can Connect message a customer who has never written?
Only with an approved template, and only where the business has the customer's permission. Outreach rules and suppression apply.