Skip to main content
Switchbord is a self-hosted WhatsApp control plane. You deploy it, connect your Meta WhatsApp Business Account (WABA), and it takes ownership of the complete messaging lifecycle: receiving inbound messages, routing them to your inbox, sending outbound messages through the Meta Graph API, running campaigns and journey automations, and recording every event for auditability and replay.

​
What Switchbord gives you

Switchbord has three main surfaces you interact with:

Operator app

The web interface for your team. Includes the inbox, contacts list, template library, campaign builder, journey editor, and workspace settings.

HTTP API

Endpoints for processing inbound webhooks from Meta, reading conversations and contacts, and compatibility integrations with external systems.

Background worker

An always-on process that schedules outbound messages, reconciles delivery states, and executes campaign and journey steps.

​
Your workspace

Everything in Switchbord is scoped to your workspace — your account and tenant boundary. All contacts, conversations, templates, campaigns, journeys, and webhook events belong to your workspace. Workspace members can hold different roles, so you can give agents inbox access, give developers API access, and keep settings locked to owners and admins. Multiple members can work simultaneously; the inbox updates in real time. A workspace can have one or more channels — each channel is a WhatsApp phone number tied to your WABA. When you add a channel, you provide your Meta access token and webhook credentials. Switchbord registers your webhook URL with Meta and starts accepting deliveries on that channel immediately.

​
How inbound messages flow

When a contact sends you a WhatsApp message, Meta delivers a webhook to Switchbord. Here is what happens:
1

Meta delivers the webhook

Meta posts the event to your Switchbord webhook endpoint (POST /webhooks/whatsapp or POST /webhooks/meta).
2

Switchbord verifies and stores the envelope

Switchbord checks the X-Hub-Signature-256 header against your signing secret. Whether the signature passes or fails, the raw envelope is stored — headers, body hash, and metadata. Nothing is discarded.
3

The event is queued for processing

Verified events are written to the outbox queue for the background worker to pick up.
4

The worker routes and processes the event

The worker classifies the event (inbound message, delivery status update, template change, conversation update) and updates the appropriate records. A new inbound message creates or resumes a conversation and appears in the operator inbox.

​
How outbound messages flow

When you or an automation wants to send a message, Switchbord follows a send-intent pattern:
1

A send intent is created

You send a message from the inbox, a campaign schedules a broadcast, or a journey step triggers a template send. Switchbord records the intent before attempting delivery.
2

The worker schedules delivery

The background worker picks up the intent, validates the template if required, and calls the Meta Graph API to send the message. Throughput limits and conversation-window rules are enforced at this step.
3

Meta confirms or rejects

The Meta response is logged against the intent record. A successful response means the message is in Meta’s delivery pipeline.
4

Delivery status webhooks update the record

As Meta delivers the message, it sends status webhooks back to Switchbord (sent, delivered, read, failed). Each status update appends to the message’s delivery history — nothing is overwritten.

​
The 24-hour service window

WhatsApp restricts when businesses can send free-form messages. Once a contact sends you a message, you have a 24-hour service window to reply with any message type. Outside that window, you can only send pre-approved template messages. Switchbord tracks the service window for every conversation. The inbox displays a warning when a conversation approaches or has passed its window, and the template send flow enforces this rule automatically. If you try to send a free-form message outside the window, Switchbord blocks it before the request reaches Meta.
To initiate a conversation with a contact who has never messaged you, or to re-engage after the 24-hour window closes, you must use an approved template. See Templates for how to sync and use them.

​
Campaigns and journeys

For scaled outbound communication, Switchbord provides two automation surfaces:
  • Campaigns let you broadcast a template to a contact audience at a scheduled time. Switchbord takes an audience snapshot when the campaign runs, validates each recipient against template eligibility, and dispatches messages through the background worker.
  • Journeys are event-triggered automation flows. You define a sequence of steps — waits, branches, and template sends — and Switchbord executes them as contacts enter the journey based on your trigger conditions.
Both campaigns and journeys emit progress events in real time so the operator dashboard stays current without manual refreshing.

​
Auditability

Every significant action in Switchbord leaves a record:
  • Webhook envelopes are stored immutably and can be replayed
  • Message delivery history is append-only and never overwritten
  • Operator actions (settings changes, credential rotations) are written to the audit log
This means you can reconstruct exactly what happened during any incident, replay failed webhook deliveries, and review who changed what and when.