API AND WEBHOOKS
The ChatBridge24 REST API
Anything that can make an HTTPS request can look up your WhatsApp Business API numbers, templates and messages and, on the Enterprise plan, send an approved template; anything that can receive one can be told about inbound messages and delivery. Two mechanisms carry most of the design: a required idempotency key, and a webhook queue that holds events rather than dropping them.
The ChatBridge24 REST API connects your own software, or any CRM, to the WhatsApp Business API numbers you have connected, with no connector to wait for. Through it your system looks up numbers, templates and messages, and its webhooks report inbound messages and delivery updates. On the Enterprise plan it also sends the same approved templates your team sends from the inbox, and every send is checked against the block list, the do-not-contact list and the number’s plan before anything is charged. Setup, end to end, is in the ChatBridge24 documentation.
If your team works in Bitrix24, the Bitrix24 WhatsApp integration is a full-featured app on the Bitrix24 Marketplace and needs no code. Every other system connects through this API and its webhooks.
Keys are scoped, and a refusal says nothing useful to a stranger
One shape of refusal for every way a key can be wrong.
A key is created in the app by an administrator, shown once, and stored as a hash — so it cannot be read back out of our database, by us or by anybody else. Each key carries scopes, so a key that only needs to read messages cannot send one. A key can also be limited to one number and given a daily send limit.
Every failure to authenticate answers the same way: a missing, malformed, unknown or revoked key gets one response, not four, so a refusal never reveals whether a key once existed on an account. The key prefix shown in the app is for your own eyes and is never a lookup path.
Every send needs an idempotency key, and that is not optional
Because the alternative is a customer receiving the same message twice.
Meta charges for template messages, so a send is not an operation that can be repeated safely — and a public API is retried by HTTP clients, job queues and load balancers that have no idea a retry costs money. So the send endpoint requires an idempotency key and refuses a request without one.
The key claims the send in a single database statement before any money moves. Three answers follow, and they are deliberately different from each other:
- A replay of a finished request returns the stored outcome, so a client that lost the response gets the real answer rather than a second message.
- A replay while the first is still in flight is refused as in-progress rather than replayed. A half-finished outcome is not an outcome.
- A refusal raised before anything was charged releases the key, as does a send that could not reach Meta at all, whose charge is returned — so the same key can simply be retried. Any other failure after the charge keeps it, because the money moved.
And the outcome of a key can be looked up afterwards, including the identifier of the charge — which is how a caller that crashed mid-request finds out what it did without sending anything.
Outgoing webhooks
Signed, retried, and switched off in a way that keeps the events.
You register an endpoint
An HTTPS URL on a host that resolves to a public address. A private address, a loopback address, a cloud metadata address or a bare IPv6 literal is refused. The address is checked when you register it and again on every delivery, at the moment of connection, because a name that resolved publicly once can resolve privately a second later. Redirects are not followed.
We sign every delivery
The signature covers a timestamp and the raw body. Verify it before parsing: once JSON has been parsed and re-serialised the bytes have changed and no signature can match again.
A failure is retried for about eleven hours
With a widening gap, in batches, across your endpoints — so one slow endpoint does not starve the others.
A dead endpoint is switched off, and its events are held
After a long run of consecutive failures spanning hours, the endpoint is disabled. Its events are kept for 30 days, not discarded: a successful test from the app within that time re-enables the endpoint and releases what it missed. An endpoint we disabled is the one case where a gap is recoverable.
The two event types
Every event in the list is one the product sends.
An endpoint subscribes to one or both of the events a WhatsApp Business API number produces:
- message.received — every new inbound message except one from a person you have blocked (history imported from a WhatsApp Business app number is not sent), with the conversation and the contact it belongs to and, on the first message of a conversation, the lead-source details read from it.
- message.status — sent, delivered, read and failed, for the messages you send.
The test button sends an event type of its own, so a successful test can never stand in for a real event. Keys follow the same rule: a scope is offered only if a route requires it, and there are five — reading numbers, templates, messages and the wallet balance, and sending messages.
What the API does not do
Four absences, so you find them here rather than at integration.
It does not get a template approved
Approval is Meta’s decision and happens against your own WhatsApp Business Account. The API sends templates that are already approved.
It does not send free text
Every send through the API is an approved template, which Meta delivers whether or not the 24-hour window is open. Free-text replies inside the window are written in the inbox.
It does not replay a webhook you lost by accident
Events are held for an endpoint we disabled. An endpoint that answered 200 and then lost the payload has been delivered to.
It has no sandbox number
You test against your own connected number, so every test runs against your own account’s templates and limits.
Questions
Which plan does the API need?
How many endpoints can one account have?
What happens if I reuse an idempotency key for a different message?
Is the wallet balance in the API?
Where it sits
WhatsApp for any CRM
The same API, framed as the route for any CRM, ERP or in-house system.
WhatsApp Business API
The platform the API sends through: numbers, templates and the 24-hour window.
ChatBridge24 documentation
Connecting a number, getting a template approved, and the setup the API sits on.
WhatsApp data protection
Where the keys are stored and what a key can reach.
Get a key
From the blog
Further reading on this subject.
WhatsApp CRM integration for any CRM
Webhooks, the REST API and the lead source a customer arrives with.