Self-hosting a WhatsApp team inbox means you run the application stack on infrastructure you control, while your team works from a web inbox instead of a shared phone.
This article explains the practical path with WATeamInbox—an open-source, MIT-licensed shared WhatsApp inbox—without turning the page into a brittle copy of every CLI flag. For commands and file-level detail, use the deployment docs.
What you are self-hosting
WATeamInbox is not a single static binary with a chat UI glued on. A typical deployment includes:
- Web app — the team inbox UI
- API — auth, business logic, search, media access patterns
- PostgreSQL — system of record (including tenant-style isolation)
- Realtime layer — live inbox updates
- NATS — durable command/event transport between API and workers
- WhatsApp worker + orchestrator — session processes that talk to WhatsApp
- Object storage — media
- Edge proxy/TLS — terminate HTTPS in production
If a guide pretends this is “docker run one container forever” with no data plane, be suspicious.
Who should self-host
Good candidates:
- teams comfortable operating Linux + Docker (or equivalent)
- companies that want customer conversation data in their account
- engineers evaluating an open-source inbox before any Cloud decision
Poor candidates (for now):
- teams that need a fully managed SLA this week
- orgs that cannot patch, back up, or monitor a small production stack
WATeamInbox Cloud is a planned managed option. The waitlist does not replace self-hosting and does not create access.
Before you touch production DNS
1. Read the risk model
WATeamInbox uses an unofficial WhatsApp client library. That enables useful multi-device style workflows for many teams, and it also means:
- WhatsApp policy/protocol changes can break connectivity
- account restriction risk is real
- no honest project can guarantee account safety
Also: WATeamInbox is independent—not affiliated with WhatsApp or Meta.
2. Separate “demo” from “business number”
Pilot with a non-critical number when you can. Migrate the primary customer line only after assignment, roles, backups, and restore drills feel boring.
3. Decide your data boundary
Write down:
- where PostgreSQL lives
- where media lives
- who can SSH / administer
- how you will encrypt disks and manage secrets
Self-hosting without access control is just a public inbox waiting to happen.
Suggested rollout order
Step A — local understanding
Run the development stack from the repository README so the moving parts are visible on your laptop. This is for learning, not production traffic.
Step B — staging on a small VM
Use the production baseline documentation:
- TLS at the edge
- secret files, not committed env files
- migrations before app start
- private data services without random port exposure
Confirm:
- you can invite a second user
- permissions behave as expected
- a WhatsApp connection can pair and receive a test message
- media fetch works
- restore from backup works on a clean machine
Step C — team pilot
Bring two or three agents into one workspace:
- define who may send
- define who may manage connections
- practice assignment and notes on real conversations
Step D — cutover
Only then point customers at the operated number as the system of record for team replies. Keep a rollback plan (previous process + backups) for the first days.
Configuration themes that matter more than cosmetics
Identity and sessions
Use strong JWT/session secrets, HTTPS-only cookies in production patterns, and least-privilege operator access. Rotate credentials when people leave.
Media storage
Plan object storage early. Customer images and voice notes are not optional extras; they dominate disk and backup size.
Realtime
If the UI does not update live, agents will open duplicate tabs and invent side channels. Validate websocket/realtime configuration under the same domain model you will use in production.
Backups
Back up PostgreSQL and object storage on a schedule you have tested. A team inbox without restores is a temporary chat mirror.
What “done” looks like for a self-hosted team inbox
You are operationally online when all of the following are true:
- Teammates log in as themselves
- A WhatsApp connection stays connected under supervision
- Inbound messages appear for authorized users
- Assignment changes ownership clearly
- Notes survive handoff
- You can restore last night’s backup
- Only intended ports face the internet
Common self-hosting mistakes
- exposing database or NATS ports to the world
- skipping migrations
- sharing one admin user across the whole support team
- never testing media
- treating unofficial WhatsApp connectivity as risk-free
- promising customers “enterprise SLA” on a single unmonitored VM
WATeamInbox’s own docs describe a single-host baseline, not a multi-region HA product. Match your promises to your topology.
How WATeamInbox positions against “just use a hosted inbox”
Hosted products optimize for speed-to-first-reply and vendor-operated reliability. Self-hosting optimizes for control.
You might still choose SaaS later. Starting open source does not require ideological purity—it requires an honest ops decision. Keep the repository and docs even if you eventually prefer managed hosting.
Next resources
- Deployment / self-hosting docs
- What is a WhatsApp team inbox?
- Open-source WhatsApp shared inbox checklist
- Cloud availability status
Bottom line
To self-host a WhatsApp team inbox, treat it like production software: data plane, secrets, backups, roles, and a staged cutover—not only a QR code login.
WATeamInbox gives you an open-source codebase and deployment guidance to do that today. Run it yourself, keep your boundary explicit, and only then decide whether a future Cloud option is worth waiting for.