Switchbord data model: entities and relationships

Switchbord organizes your WhatsApp operations around a small set of core entities. Understanding how these entities relate to each other will help you navigate the operator app, use the API effectively, and reason about what happens when messages are sent or received.

​

Workspace

A workspace is your account and the top-level boundary for all your data. Every contact, conversation, channel, template, campaign, journey, and webhook event belongs to a single workspace. Workspace members are the people on your team with access to the operator app or API. Each member has a role that controls what they can see and do:

​

Channel

A channel is a WhatsApp phone number connected to your workspace. Each channel maps to a Meta WABA ID and a specific phone number. When you add a channel, you provide your Meta access token and webhook credentials. Switchbord uses those credentials to:

• Verify and receive inbound webhooks from Meta on that number
• Dispatch outbound messages through the Meta Graph API
• Sync template status updates from Meta

A workspace can have more than one channel. Conversations, messages, and campaigns are always associated with a specific channel.

​

Contact

A contact is a WhatsApp user who has sent you a message or who you have messaged. Contacts are identified by their WhatsApp phone number. Each contact record includes:

• Phone number — the normalized WhatsApp identifier
• Display name — from Meta or set by your team
• Tags — labels you apply for segmentation and filtering
• Custom attributes — arbitrary key-value properties you define
• Opt-out state — whether the contact has unsubscribed from outbound messaging

​

Conversation

A conversation is a thread between one of your channels and a contact. Each conversation has:

• Status — open, resolved, or snoozed
• Assignment — the team member responsible for this conversation
• Service window — whether the 24-hour window for free-form messaging is open or closed
• Message history — the full ordered list of messages exchanged in this thread

Conversations are created automatically when a contact messages you for the first time, or when you initiate a template send to a contact. You cannot manually create an empty conversation — they only exist when there is at least one message.

​

Message

A message is an individual WhatsApp message within a conversation — either inbound (from the contact) or outbound (from your team or an automation). Messages are stored as an append-only ledger: once written, a message record is never changed. Delivery events (sent, delivered, read, failed) are recorded as separate entries against the message, so the full delivery timeline is always available. Each message records:

• Direction (inbound or outbound)
• Content (text, media, template, interactive, etc.)
• Timestamp
• Delivery status events

​

Template

A template is a pre-approved WhatsApp message format that Meta requires for messaging outside the 24-hour service window. Templates are created and approved in Meta’s Business Manager, then synced into Switchbord automatically. In Switchbord, a template record includes:

• The template name and language
• The approval status from Meta (approved, pending, rejected)
• The content structure (header, body, footer, buttons)
• Variable placeholder definitions

You use templates when initiating conversations, running campaigns, or sending from a journey step where the service window is closed.

​

Campaign

A campaign is a scheduled outbound broadcast that sends a template to a defined contact audience. When a campaign runs:

1. Switchbord takes a snapshot of the audience at execution time
2. Each recipient is validated against the template and their opt-out state
3. Messages are dispatched through the background worker, respecting throughput limits
4. Delivery results are tracked per recipient

Campaigns are one-time sends — they are not recurring by default. Use journeys for ongoing automation.

​

Journey

A journey is an automated messaging flow that runs when a contact matches a trigger condition. A journey consists of a series of steps:

• Wait — pause execution for a defined duration before proceeding
• Branch — fork the flow based on contact properties or event conditions
• Send template — dispatch an approved template to the contact

Journeys execute in the background worker. When a contact enters a journey, Switchbord creates an execution record and advances it step by step, respecting any waits and branch conditions you defined.

​

Webhook event

A webhook event is a stored record of an inbound delivery from Meta or a partner system. Switchbord stores every inbound webhook envelope — regardless of whether it passes signature verification — so you have a complete record of what arrived and what happened to it. Each webhook event record includes:

• The raw envelope (headers, body hash, query parameters)
• Verification status (passed or failed)
• Normalization status (which event family Switchbord assigned)
• Processing status (processed, failed, replayed)
• Attempt count and replay history

Storing webhook events as first-class records is what enables Switchbord’s replay capability: if processing fails, you can reprocess the original event from the operator dashboard without Meta needing to redeliver it.

​

Outbox job

An outbox job is an asynchronous task waiting to be processed by the background worker. When Switchbord needs to do something asynchronously — send a message, advance a journey step, sync template state — it writes an outbox job rather than doing the work inline. Outbox jobs are explicit records, not hidden queue internals. This means you can inspect queue depth, identify stuck jobs, and understand what work is pending at any point.

​

Audit log

The audit log records operator and system actions that affect workspace configuration or sensitive data. Actions logged include:

• Workspace settings changes
• Channel credential additions and rotations
• Member role changes
• Template sync operations
• Manual webhook replays

Audit log entries are append-only and cannot be deleted.