How the two relate, which complexity Ghala absorbs, where it stops, and when to reach past it to Meta directly.
Meta's WhatsApp Cloud API is the messaging platform. It is the thing that actually delivers a message to a handset, and every message Ghala sends goes through it.
Ghala is an application built on that platform, plus a narrow developer API for the numbers connected through it. The Ghala Developer API is not a proxy for Meta's API and does not aim to be: it exposes the two operations an integration needs (send a message, read the sendable templates) and leaves the rest to the dashboard.
If you are looking for a general-purpose Meta Business Management client, Ghala is not it. If you want to send from and react to a number that Ghala already runs, without learning Meta's onboarding, token, and webhook model, this is the shorter path.
These are the things you would otherwise build yourself against Meta:
| Meta complexity | What Ghala does |
|---|---|
| Business Portfolio, WABA, and phone-number registration | Embedded Signup wizard, PIN registration, and a live flag that tells you whether the number can actually send |
| System-user tokens, token expiry, and permission scopes | One access token per connected number, revealed in the dashboard, rotated by reconnecting |
Webhook verification handshake, X-Hub-Signature-256, and Meta's envelope |
Signed Ghala event deliveries with a stable delivery id, or an override that hands you Meta's raw feed |
The 24-hour window, and Meta error 131047 after the fact |
A local 409 outside_messaging_window before the send is attempted |
| Working out which templates can actually be sent right now | GET /api/v2/templates?sendable=true, with unsendable_reason in plain words |
| Retry storms sending a customer the same message twice | Idempotency-Key, with replay and in-flight handling |
| Your integration and an AI assistant answering the same customer at once | A send through the API stands the agent down for that customer automatically |
| Template review state, quality scores, and media header uploads | Dashboard template management, with quality_score surfaced on the API |
The Ghala Developer API does not currently expose Meta Business Management operations. There is no endpoint for creating a WABA, registering a phone number, editing a business profile, managing a catalogue, uploading media to Meta's media store, or authoring templates.
Some of those exist in the Ghala dashboard. Some do not exist in Ghala at all. The capability matrix is the per-feature answer to "can I do this, and where".
This is the decision most integrations get wrong, so it is worth being precise. Ghala's default is that Meta delivers a number's events to Ghala, which is what powers the inbox, the AI agent, orders, and analytics.
DEFAULT — everything runs inside Ghala
Customer ──▶ Meta Cloud API ──▶ Ghala ──▶ inbox, AI agent, orders, analytics
▲
└── POST /api/v2/messages ◀── your backendFrom there you have two ways to also get the data onto your own server.
Event subscription — a signed copy, additive. Ghala processes the event first, then POSTs you a copy. Everything in the product keeps working.
Customer ──▶ Meta Cloud API ──▶ Ghala ──┬──▶ inbox, AI agent, orders
│
└──▶ your endpoint (signed copy)WhatsApp callback override — a replacement, subtractive. Ghala points Meta at your URL instead of its own. You get Meta's raw envelope, and Ghala stops receiving that number's messages entirely.
Customer ──▶ Meta Cloud API ──▶ your endpoint (raw Meta format)
Ghala: inbox, AI agent, orders all PAUSE for this numberUse an event subscription when you want to mirror conversations into your own CRM, trigger your own workflows, reconcile order state, or drive analytics, and you still want the Ghala inbox and AI agent working. This is the right answer for almost every integration.
Use the raw Meta callback override when you are deliberately replacing Ghala's message handling for a number: you are building your own bot end to end, you need message types or fields Ghala's event payloads do not carry, or you need Meta's exact envelope for an existing Cloud API integration you are migrating.
The two are mutually exclusive. Registering an event subscription is refused while an override is in place, because an override means Ghala never sees the event to copy.
The override is the single most consequential setting on a number. While it is active there is no AI reply, no inbox thread, and no order capture for that number. Removing the override hands the number back.
Both are configured in the dashboard: Developer → Events for subscriptions, Developer → Webhooks for the override. Neither is manageable through /api/v2.
The common case. One team, one connected number, one access token held by your backend.
┌─────────────────────────────────────────────┐
│ Your backend │
│ GHALA_ACCESS_TOKEN (one secret) │
└──────────────┬──────────────────────────────┘
│ Bearer token
▼
POST /api/v2/messages
│
▼
┌─────────────────────────┐
│ Ghala team "Acme" │
│ Number +255 712 ... │──▶ Meta Cloud API ──▶ customers
└─────────────────────────┘
│ event subscription
▼
https://acme.example/ghala/webhookOne token, one signing secret, one endpoint. Nothing to route.
A business with a sales line and a support line, or one number per country. Each connected number has its own access token and its own signing secret. There is no team-wide key that reaches both.
┌───────────────────────────────────────────────────┐
│ Your backend │
│ tokens: { sales: "...", support: "..." } │
└───────┬───────────────────────┬───────────────────┘
│ │
▼ ▼
┌────────────────┐ ┌────────────────┐
│ Number: sales │ │ Number: support│
│ +255 712 ... │ │ +255 713 ... │
└───────┬────────┘ └───────┬────────┘
│ │
└───────────┬───────────┘
▼
one endpoint, or one per numberYou can point every number's subscription at a single endpoint. Route on the payload's own identity fields rather than the URL, or register a distinct path per number so the URL itself tells you which one it is.
You are a software vendor and each of your customers has their own WhatsApp number. Each client's number lives in their own Ghala team, with its own token, its own signing secret, and its own billing.
┌──────────────────────────────────────────────────────────────┐
│ Your platform │
│ │
│ tenants table │
│ ┌────────────┬──────────────┬───────────────────────────┐ │
│ │ tenant_id │ phone number │ secret ref (vault) │ │
│ ├────────────┼──────────────┼───────────────────────────┤ │
│ │ acme │ 255712... │ vault://ghala/acme │ │
│ │ bakari-ltd │ 255713... │ vault://ghala/bakari-ltd │ │
│ │ zawadi │ 255714... │ vault://ghala/zawadi │ │
│ └────────────┴──────────────┴───────────────────────────┘ │
└───────┬──────────────────┬──────────────────┬────────────────┘
│ │ │
▼ ▼ ▼
Ghala team: Acme Ghala team: Bakari Ghala team: Zawadi
number + token number + token number + token
│ │ │
└──────────────────┼──────────────────┘
▼
https://you.example/ghala/:tenant/webhookNumbers can sit in different WABAs and different Meta Business Portfolios; Ghala scopes on the connected number, not on the portfolio above it. Each team's plan must independently grant the API access entitlement.
Multiple Numbers and Multi-Tenant Platforms has the working token-routing code, credential isolation rules, and rotation procedure.
Three situations justify it:
Everything else — sending, replying, reacting to inbound messages, checking what you may send — is what the Ghala API is for, and doing it through Ghala keeps the inbox, agent, and orders working alongside your code.