Overview
Switchboard is the WhatsApp server Atrix products share. One deployment, many projects, each scoped to its own numbers.
It is a control plane over a hardened WhatsApp engine: per-project isolation, durable delivery in both directions, a number registry with sending caps, request attribution, an audit trail, metrics and alerting. Open-source components and their licences are listed under licences.
Why it exists#
The engine underneath has no tenancy. A single global key can list, inspect and delete every instance on the box, so two products sharing one deployment meant either could destroy the other’s paired numbers. A shared server needed a control plane before it could be shared at all.
The engine was also vendored inside the first product that needed WhatsApp, and the second product wrote its own client against it — the same integration maintained twice, in two repos, diverging.
Three credentials, three scopes#
Getting these confused is the most common early mistake. All three go in an apikey header.
| Credential | Reaches | Held by |
|---|---|---|
| Root key | The whole deployment — projects, keys, every number | Operators only |
| Project key | One project’s instances, queue, usage and audit trail | A project’s backend |
| Instance token | A single number — send, chat, group | A sender or worker |
The split is not ceremony. An instance token ends up in workers, crons and handlers; a project key can delete a paired number. The credential that spreads furthest is the one that can do least.
Never put the root key in a project
/v1 is control operations only.The rules that prevent the usual mistakes#
Twelve of them, each learned by breaking something real. The ones that cost the most time:
| Rule | Why |
|---|---|
| Stop polling the QR once it says paired | Asking again tears the pairing down about four seconds after it succeeded. |
| Never connect an already-connected instance | It unlinks the device. /v1 returns 409 rather than doing it. |
| Record the phone at create time | The JID only appears after the scan, so without it nobody knows which SIM to use. |
| Dedupe on X-Switchboard-Delivery | Delivery is at-least-once. Exactly-once would mean losing messages instead. |
| Never answer 5xx for your own bug | That is a retry storm for a message that was fine. |
| Retry a 503, and only a 503 | That is a number moving between replicas. |