ChatBridge24

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.

Developer API v1 · 2 live keys POST /api/v1/waba/messages Authorization: Bearer cb24_live_●●●● Idempotency-Key: 7f3c1a9e-4b2d { "to": "+971504182…", "template": { "name": "viewing_confirmed", "language": "en", "params": ["Layla", "Tue 4pm"] } } 200 · THE SAME KEY NEVER SENDS TWICE { "waMessageId": "wamid.HBgM…", "status": "sent", "chargedCents": 0, "billingMode": "direct" } OUTGOING WEBHOOKS · EVERY ATTEMPT RECORDED message.received https://crm.example.com/hooks/wa 200 message.status https://crm.example.com/hooks/wa 200 message.received https://old.example.com/hooks RETRY 3 OF 8
The REST API: a send carrying an idempotency key, the JSON it answers, and the outgoing webhook deliveries with their retry state. A drawing of the product.

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.

01

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.

02

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.

03

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.

04

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?
Keys, the read routes and the webhooks work on every WhatsApp Business API plan. Sending a template through the API needs the number on the Enterprise plan; a trial does not include it. There is no separate charge for the API: it sends through the same number, under the same subscription, as the inbox, and Meta’s message charges apply as they do to any template.
How many endpoints can one account have?
Up to ten, on every WhatsApp Business API plan — enough for a production and a staging consumer, with room to move between them. An endpoint can receive the events of every number on the account, or of one.
What happens if I reuse an idempotency key for a different message?
The request is refused and nothing is sent. A key belongs to one request: the same key with a different body is answered with a conflict. Generate a fresh key for every message you mean to send, and reuse it only to retry that same message.
Is the wallet balance in the API?
Yes, read-only. Where Meta bills you directly, nothing is metered on our side, so the balance and the free allowance are returned as null rather than as zero — an integration that waits for a positive balance would otherwise never send.

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.

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.