Integration overview

WhatsTIG treats every product — your SaaS, CRM or internal tool — as an API consumer. It has no product-specific logic: it does not know what a tenant or a workspace is. Your product maps its own tenants to WhatsTIG instances through externalReference.

 Your product (SaaS, CRM, ...)                             WhatsTIG
┌──────────────────────────────────┐   API key    ┌──────────────────────────────┐
│ your users & permissions         │  (server)    │ Project "myapp-production"   │
│ tenant 101 ── settings/whatsapp ─┼─────────────►│   instance wa_A  ext=tenant-101│
│ tenant 102                       │              │   instance wa_B  ext=tenant-102│
│ notification service ────────────┼── /v1/msgs ─►│   send lanes per instance      │
│ webhook receiver ◄───────────────┼─ signed POST ┤   outbox → webhooks            │
└──────────────────────────────────┘              └──────────────────────────────┘

Ownership model

Rule	Consequence
Every instance belongs to exactly one project, and every project to one organization	A key of one project can never see another project's instances
externalReference is unique per project	The same tenant-101 in two projects refers to two different instances
Your product authenticates its own users and checks their permissions	WhatsTIG independently checks that the API key's project owns the instance
Deleting an instance affects only that instance	Deleting tenant 101's instance never touches tenant 102's
Instances cannot be moved between organizations through the API	Moving a linked number into another WhatsTIG account is not available yet

Delegated provisioning: your backend creates and manages instances for your users within your project. Your users do not need WhatsTIG accounts.

Integration scenarios

	Scenario	Organization / project	Who links the phone	Guide
D	Standalone customer uses the WhatsTIG dashboard	Customer's own org and projects	The customer, in the WhatsTIG dashboard	below
E	External developer integrates their SaaS	Developer's own org; one project per environment	Their users, via the developer's app	below + REST

When one customer needs several numbers (for example support and notifications), create one instance per number and set externalReference to <customerId>:<purpose>, such as cust-12:support and cust-12:notifications.

Lifecycle checklist (all scenarios)

Step	API
Provisioning	Create an organization and project in the dashboard
Authentication	Create a project API key with the scopes you need; store it in your backend's secret store
Tenant mapping	POST /v1/instances { name, externalReference: "<your tenant id>" } with Idempotency-Key: create-<tenant id>
Lookup	GET /v1/instances?externalReference=<tenant id>
QR connection	POST .../connect, then show GET .../qr (proxied), or send a hosted connect-sessions link
Session restoration	Automatic; nothing to do. Watch instance.logged_out to ask the tenant to re-link
Sending	POST /v1/messages with your notification id as Idempotency-Key and clientReference
Receiving events	One webhook endpoint per project, verify signatures, route by externalReference
Error handling	See Errors and Reliability
Disconnecting	POST .../logout when the tenant wants to unlink; disconnect to pause
Cleanup	DELETE /v1/instances/{id} when the tenant is deleted (unlinks the phone, fails queued messages)
Usage tracking	GET /v1/usage?instanceId=... per tenant, or count message.sent webhooks per externalReference

Scenario D — standalone customer

1. Register at the dashboard, verify email, create an organization (a Default project is created).
2. WhatsApp instances → Add instance → Connect WhatsApp, scan the QR with the phone.
3. Send a test message from Messages. Add teammates in Team.
4. To automate: create an API key under API keys and follow the quick start; register a webhook under Webhooks.
5. Monitor connection health on Overview (needs-attention list) and usage under Usage.

Scenario E — external developer

1. Create an organization and one project per environment (e.g. myapp-staging, myapp-production).
2. Create an API key per environment (instances:*, messages:*, webhooks:*, events:read, media:*).
3. For each of your customers create an instance with externalReference = <your customer id>.
4. Let your customer link their phone: proxy GET /qr into your UI (keep the key server-side) or redirect them to a hosted connect link with your returnUrl.
5. Send with idempotency keys; receive and verify webhooks; reconcile with /v1/events.
6. Respect the acceptable-use policy on behalf of your customers: you are responsible for their sending behaviour.

Language guides: Next.js · Node.js / TypeScript · ASP.NET Core / C# · Python / FastAPI · Generic REST