WhaBuzz
Start trial

WhatsApp API for multi-tenant SaaS platforms

By · Published · Updated · 5 min read

A multi-tenant WhatsApp integration is a SaaS product that sends WhatsApp messages on behalf of many client businesses, each on its own phone number. In WhaBuzz terms every client is a tenant with its own numbers, keys, webhook endpoints, event log and bill, and your platform manages them all with one app key.

What does multi-tenant mean for WhatsApp?

Your product has customers, and each customer is a business with its own WhatsApp Business Account (WABA) and number. Their messages, templates and quality rating belong to that number at Meta. Your platform must keep them apart: customer A's inbound messages must never reach customer B's webhook, and customer A's charges must not land on customer B.

Two Meta facts shape the design. According to Meta's Solution Provider overview, Tech Providers do not have credit lines: clients onboarded by a Tech Provider provide their own payment method after onboarding, and Meta bills them for API usage. So each customer ends up with their own Meta billing relationship. And per Meta's throughput page, Cloud API supports up to 80 messages per second per registered business phone number by default, so capacity grows with each connected number rather than being shared across your platform.

Instead, clients onboarded by Tech Providers must provide their own payment method after onboarding is complete.

How does WhaBuzz model tenants?

A tenant is one business account: its numbers, keys, webhook endpoints and event log. Direct customers have exactly one. Platforms get an app key, issued by a WhaBuzz administrator, that is not tied to a single business.

You create a tenant per end customer:

curl -X POST https://api.whabuzz.com/v1/tenants \
  -H "Authorization: Bearer $WHABUZZ_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sunrise Clinic","external_ref":"org_4812"}'
bash

external_ref is your own id for the customer, so you can map tenants back to your database. After that, every tenant route takes a header naming the business: X-WhaBuzz-Tenant: <tenant_id>. WhaBuzz checks that the tenant belongs to your app. A missing header on a tenant route is 400 invalid_request. The Tenants guide and Authentication cover the details.

How does each business connect its own number?

Each customer connects through Meta's Embedded Signup, a popup where a person logs in with Facebook, picks or creates a WABA, adds a number and verifies it by SMS or voice. Per the Numbers guide, platforms should not run that popup in their own app. Create a hosted connect session instead:

curl -X POST https://api.whabuzz.com/v1/connect-sessions \
  -H "Authorization: Bearer $WHABUZZ_APP_KEY" -H "X-WhaBuzz-Tenant: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"return_url":"https://yourapp.example/whatsapp/done"}'
bash

The response carries a url on app.whabuzz.com, valid for one hour. Send your customer there. Afterwards they return to your return_url with session_id and status=connected or failed. You can poll the session or wait for the number.connection event.

WhaBuzz exchanges the signup code for a business token, checks it, stores it encrypted and subscribes the WABA to its webhooks. The token never reaches your server.

One date matters here. Meta says Embedded Signup v2 and v3 are deprecated on 15 Oct 2026 and tells integrations to move to v4. If you run the popup yourself, that migration is yours. With the hosted link, it is not.

What does each tenant get for webhooks?

Each tenant has its own webhook endpoints and event log, and events are delivered only to the tenant they belong to. You can point every tenant at one URL on your platform, or give each its own. In both cases the envelope tells you which tenant and which number an event is for, so your handler routes by those fields.

Signing, retries and replay work per endpoint, as described in WhatsApp webhooks that never lose an event. Deliveries are HMAC-SHA256 signed in the X-WhaBuzz-Signature header, retried for 24 hours on failure, then marked dead with an email. Replay is available within the tenant's retention setting of 30, 90, 180 or 365 days.

Retention is also per tenant. A healthcare customer can choose 30 days while another keeps the default 90.

How is a multi-tenant platform billed?

Billing is per tenant. A number is billed while its state is connected, at ₹500 a month for a tenant's first number and ₹250 for each additional one, excluding GST (18% is added). There is nothing per message. Numbers that are pending or disconnected are not billed.

Meta's own charges are separate. Based on Meta's rate card effective 1 Oct 2026, a delivered marketing message to India costs ₹0.8631 and a utility message ₹0.115, charged by Meta to each customer's own Meta account. WhaBuzz does not mark these up or see them on an invoice.

A number counts as connected only when the WABA is subscribed, the number is registered, an active webhook endpoint is subscribed to message.inbound or *, the token is valid and the tenant is active. If any check fails, connection_detail says which. Sending from such a number answers 409 number_not_connected.

What should a platform decide first?

Four choices come before code.

  1. Who owns the WABA? Customers should own theirs. That keeps the number portable if they leave your platform.
  2. Who handles opt-in? WhaBuzz does not manage opt-in or opt-out lists. Your platform stores consent per customer and per recipient.
  3. How do you map tenants? Store tenant_id against your own customer id, and set external_ref at creation.
  4. What happens at suspension? A suspended tenant cannot send, but inbound messages are still forwarded. Decide what your product shows.

WhaBuzz is an API, not an inbox or campaign tool, so your product supplies the interface. If you are comparing models, BSP vs Tech Provider vs Cloud API explains who bills what, and WhaBuzz vs Meta Cloud API direct covers building this layer yourself.

Frequently asked questions

Does every customer need their own WhatsApp number?

Yes. Each tenant connects its own number through Meta's Embedded Signup. WhaBuzz bills per connected number, and Meta's charges go to the customer's own Meta account.

Can I use one webhook URL for all tenants?

Yes. Each tenant has its own endpoints, so you can register the same URL for each one. Route inside your handler using the tenant and number fields in the event envelope.

Who pays Meta for the messages?

The customer. Meta bills the business that owns the Messaging account, at Meta's rate. WhaBuzz neither marks this up nor invoices it.

Do I run the Embedded Signup popup myself?

No. A hosted connect session sends your customer to a WhaBuzz page that runs Meta's popup, then returns them to your return_url.

Can a tenant be paused?

WhaBuzz can set a tenant to suspended, for example after an unpaid invoice past grace. Sends stop, and inbound messages are still forwarded.

Related posts