Skip to content
Resources · Blog

WhatsApp API for SaaS: One Number per Tenant 

How to add WhatsApp to a multi-tenant SaaS product: one number per customer, hosted QR connect links, idempotent sends, and signed webhooks routed by tenant.

November 10, 2026 5 min read
WhatsAppSaaSEngineeringWhatsTig

A WhatsApp API for SaaS has a job that a single-business integration never faces: your product has many customers, and each one wants to message its own customers from its own number. A school wants parents to see the school's name. A clinic wants appointment reminders to come from the reception number patients already have saved. Routing everything through one shared gateway number fails that test, and so does asking every customer to open an account with a messaging vendor. We hit this problem in our own products, EduTig for schools and MailTig for outreach, and the pattern we settled on is now how WhatsTig works for any software product. This guide walks through it in order, including the parts that break first.

One Instance per Tenant, Keyed by Your Own ID

Start with the data model, because everything else depends on it. In WhatsTig an instance is one linked WhatsApp number. Create one per tenant and set its externalReference to your own tenant ID, such as tenant-101. That reference comes back on every webhook event, so your code always knows whose message it is handling, and a lookup by externalReference finds the instance later even if you never cached its ID. Create it with an Idempotency-Key derived from the tenant, such as create-tenant-101, so a provisioning job that runs twice creates nothing new. When one customer needs several numbers, say support and notifications, use a composite reference like cust-12:support and cust-12:notifications. Keep one project per environment, for example myapp-staging and myapp-production, each with its own API key and webhook endpoint. References are unique per project, so the two environments never collide, and a key from one project can never see another project's instances. Your customers never need a WhatsTig account: your backend provisions and manages instances on their behalf.

Let Customers Link Their Own Number

Linking is where a tenant forms its first impression, and there are two good ways to do it. The first keeps everything inside your UI. Your backend checks that the signed-in user may manage that tenant and starts the connection, and your settings page polls your own backend every two or three seconds. When the status is QR_REQUIRED, the backend fetches the QR code and returns it as an image; the administrator scans it with the business phone, and the status moves to CONNECTED, which also arrives as an instance.connected webhook. The API key stays on your server and the browser only ever sees an image. The second option is a hosted connect link: one API call returns a short-lived URL, valid for 60 to 1,800 seconds, to a page that shows only that tenant's QR code and status, then sends the user back to your app. Treat the link as a secret, because it is the only credential. A pairing code can replace the QR scan for users who prefer it. After that first scan there is little to maintain, since sessions are stored encrypted and restored automatically after restarts and deployments. The event to handle is instance.logged_out, which means the device was unlinked from the phone; show a reconnect banner in that tenant's settings and run the same flow again.

Sends That Survive Retries

Every notification your product sends should carry its own ID twice: as the Idempotency-Key header and as the clientReference field. If a background job retries after a timeout, the repeated key returns the original response instead of sending the parent a second absence alert. Read the response for what it is. A 202 with status QUEUED means the message is stored durably and will be sent asynchronously; it does not mean delivered. Retry network errors, 429s, and 5xx responses later with the same key, and treat most other 4xx responses, such as a malformed phone number, as data to fix rather than something to retry. Give time-sensitive messages an expiry, because an absence alert is useless tomorrow. Then plan for the state most APIs pretend does not exist. If a worker stops in the middle of a send, nobody can know whether WhatsApp received the message, so WhatsTig marks it UNKNOWN and never resends it automatically; a later receipt upgrades it if it did arrive. Your product should show something like delivery unconfirmed and let a business rule decide, rather than resend and risk a duplicate.

One Webhook Endpoint, Routed by Tenant

You do not need an endpoint per customer. Register one per project and route each event by its externalReference: message.delivered, message.read, message.failed, and message.unknown update the notification matched by clientReference; message.received goes to the right tenant's reply handler; instance.logged_out flags that tenant's settings. Verify every delivery before trusting it. The WhatsTig-Signature header carries a timestamp and an HMAC-SHA256 of that timestamp joined to the raw request body, so compute it over the raw bytes before any JSON parsing, reject timestamps older than five minutes, and compare in constant time; both official SDKs include a verifier. Delivery is at least once, so deduplicate on the event ID. Events can also arrive out of order, so use their occurredAt timestamp and the order QUEUED, SENT, DELIVERED, READ to ignore regressions. Answer with a 2xx within ten seconds and push slow work onto a queue. A failed delivery is attempted eight times over about 16 hours, then marked dead and kept for replay, and the event log covers 30 days, so an outage on your side becomes a reconciliation job rather than lost data.

Usage, Billing, and Offboarding

Usage per tenant comes from the usage endpoint filtered by instance, or from counting message.sent events by externalReference, which is enough to reconcile messages against what each customer's plan includes. Offboarding has two moves: log out when a tenant wants to unlink its number, and delete the instance when the tenant leaves, which unlinks only that number and fails its queued messages without touching any other tenant. If messaging is part of your own pricing, the partner route goes further, and EduTig uses it. Each school gets its own WhatsTig organization, EduTig grants the monthly messages its package includes through a server-to-server partner API, and an Open WhatsTig button signs staff into the dashboard without a second password. A package upgrade changes the allowance immediately, and a school that outgrows it can buy a WhatsTig plan on top.

The Responsibility You Take On

An integration like this makes you responsible for how your customers send, so set the expectations inside your product, not only in your terms. WhatsTig uses Baileys, an unofficial implementation of the WhatsApp Web multi-device protocol, and is not affiliated with, authorized, or endorsed by WhatsApp or Meta. Accounts can be restricted, the protocol can change, and delivery is never guaranteed. That makes it a good fit for messages people expect, such as attendance alerts, order updates, reminders, and replies, and a poor fit for unsolicited promotion, which gets numbers banned at any sending rate. Pass consent through to the contact record when you have it, honor STOP on every number, and keep the official WhatsApp Business Platform in mind for tenants in regulated or high-stakes sectors, where a restricted number would be an incident rather than a bad day. We explain how we weighed that trade-off, and what the platform does to contain it, in the WhatsTig case study. If you are also building the product around the integration, our custom software team builds this kind of multi-tenant plumbing for clients.

Have a project that needs this kind of thinking applied to it?