What you’ll need
- Admin access to your Meta Business Manager and a verified WABA
- A phone number approved for the WhatsApp Business API
- Access to your Switchbord workspace as an owner, admin, or developer
Step 1: Prepare Meta
Confirm your WABA and phone number
Sign in to Meta Business Manager and confirm that your WhatsApp Business Account is active and the phone number you want to use is registered and approved. You cannot connect a number that is still pending review.
Generate a Meta access token
In the Meta for Developers dashboard, open your app and navigate to WhatsApp > API Setup. Generate a permanent (system user) access token with the
whatsapp_business_messaging and whatsapp_business_management permissions. Copy this token — you will paste it into Switchbord.Choose a webhook verify token
Create a short secret string to use as your webhook verify token. This is a value you choose yourself — Meta will send it back to your webhook URL to confirm ownership. You will enter the same value in both Meta and Switchbord, so keep it handy.
Copy your Switchbord webhook URL
Open Switchbord and navigate to Setup at
/setup. The page displays your workspace webhook URL. Copy this URL — you will paste it into Meta in the next step.The webhook URL is specific to your Switchbord deployment. It does not change unless you redeploy to a different host.
Register the webhook in Meta
In the Meta for Developers dashboard, go to your app’s Webhooks section. Add a new webhook subscription:
- Callback URL: paste the URL you copied from Switchbord Setup
- Verify token: enter the verify token you chose in the previous step
messages and message_status (also called message_deliveries, message_reads) fields under the WhatsApp Business Account object. Click Verify and save — Meta will send a challenge to your webhook URL. Switchbord handles the challenge automatically.Step 2: Configure Switchbord
Open Setup or Settings
- First-time setup: navigate to Setup in the sidebar. This page walks you through the full connection checklist.
- Updating credentials: open Settings and go to the Provider tab.
Enter your provider credentials
Fill in the three required fields:
Click Save (or the equivalent save action on the form). Switchbord sends these values to the server, where they are written into Vault. They are never returned to the browser after this point.
| Field | Value |
|---|---|
| Meta access token | The system user token you generated in Meta |
| Webhook signing secret | The app secret from Meta App Settings |
| Meta verify token | The string you chose and entered in the Meta webhook configuration |
Validate the configuration
Click Validate configuration. Switchbord calls the Meta Graph API to confirm the access token is valid and has the required permissions.After validation:
- Each credential shows a configured or missing status — never the raw value
- The validation result shows the last check time and any error codes if the token is invalid
Confirm the webhook endpoint
Back in the Meta for Developers dashboard, verify that the callback URL shown in your webhook subscription matches exactly what Switchbord displays in Setup. A mismatch here will cause inbound messages to be delivered to the wrong endpoint.
How Switchbord stores your credentials
Switchbord never echoes stored secret values back to the browser. After you save credentials, the UI shows only:- Configured or Missing — whether a value has been stored
- Source — whether the value came from Vault (workspace-managed) or from a server environment variable (bootstrap fallback)
- Last validation status — the result and timestamp of the most recent validation check
Rotating credentials
You can rotate any credential without redeploying Switchbord:- Generate the new token or secret in Meta.
- Open Settings and go to the Provider tab.
- Enter the new value and save.
- Click Validate configuration to confirm the new credential is accepted.