Skip to main content
The Contacts page at /contacts is your directory of WhatsApp users who have interacted with your workspace or been synced from an external system. Each contact record is keyed to a phone number in E.164 format and holds the information Switchbord needs to send messages, apply audience targeting, and track opt-out state.

​
Contact profile

Each contact has a profile page that shows:
  • Phone number — the contact’s WhatsApp number in E.164 format (e.g. +15551234567). This is the unique identifier for the contact and cannot be changed.
  • Display name — a human-readable name, either provided when the contact was synced or filled in from the contact’s WhatsApp profile.
  • Tags — one or more labels used for segmentation and filtering.
  • Custom attributes — additional key-value fields synced from your systems (e.g. plan, region, customer_id).
  • Opt-out state — whether the contact has opted out of receiving outbound messages.
  • Conversation history — a link to all conversations with this contact.

​
Opt-out handling

Switchbord tracks opt-out state automatically. When a contact sends an inbound message containing a stop word (such as “STOP” or “UNSUBSCRIBE”), Switchbord marks them as opted out.
Opted-out contacts are blocked from receiving outbound messages. Any attempt to send to an opted-out contact — whether from the inbox, a campaign, or a journey — will be rejected before it reaches Meta. This behavior cannot be overridden from the UI.
The opt-out state is visible on the contact profile and in the contact list. If a contact sends a message after opting out (re-engaging), Switchbord can restore their opt-in state automatically depending on your configuration.

​
Tags

Tags are the primary tool for segmenting contacts. You can add or remove tags from a contact profile manually, or sync them via the API. To tag a contact from the Contacts page:
  1. Click the contact to open their profile.
  2. Click Add tag in the tags section.
  3. Select an existing tag or type a new one and press Enter.
  4. The tag is saved immediately.
Tags appear in the contact list and can be used to filter contacts, build segments, and target campaigns or journeys.

​
Segments

Segments are dynamic groups of contacts defined by tag and attribute rules. When you create a segment, Switchbord evaluates the rules against your contact list each time the segment is used — so segments always reflect the current state of your contacts. Segments are used in:
  • Campaigns — to define the audience for a broadcast
  • Journeys — to control which contacts enter an automated flow
You can view and manage segments from the Contacts page by navigating to the Segments tab.

​
Bulk actions

To act on multiple contacts at once:
  1. On the Contacts page, check the boxes next to the contacts you want to act on (or use Select all to select the full filtered list).
  2. Choose an action from the bulk action toolbar:
    • Add tag — apply one or more tags to all selected contacts
    • Remove tag — remove a tag from all selected contacts
    • Export — download the selected contacts as a CSV file
Use the filter controls to narrow the contact list by tag or attribute before selecting all, so your bulk action applies to exactly the right audience.

​
Syncing contacts via API

You can create or update contacts programmatically using the Switchbord API. This is the recommended approach when syncing from a CRM, e-commerce platform, or other external system. Use the POST /compat/contact endpoint to upsert a contact by phone number. If a contact with that phone number already exists, Switchbord updates the record. If not, it creates a new one. 
curl -X POST https://your-switchbord.example.com/compat/contact \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "name": "Jane Smith",
    "tags": ["vip", "newsletter"]
  }'
The REST API also exposes a more complete upsert surface at PUT /api/v1beta/contact/, which supports custom attributes and additional fields. See the API Reference for the full request schema and response format.
Contacts synced via the API appear in the Contacts page immediately. Tags included in the sync payload are merged with any tags already on the contact — existing tags are not removed unless you explicitly remove them.