> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect WhatsApp
> Complete step-by-step guide for connecting a WhatsApp Business number to Switchbord — including Meta setup, credential configuration, and troubleshooting.
# Connect WhatsApp
This guide walks you through the complete process of connecting a WhatsApp Business number to Switchbord.
It covers what to configure in Meta Business Suite, what to enter in Switchbord settings, and how to
diagnose the most common errors.
This process involves both Meta (developers.facebook.com / business.facebook.com) and the Switchbord
settings UI. Have both open in separate tabs. The full setup takes 15–30 minutes the first time.
***
## Complete Setup — Step by Step
Follow these steps in order. Skipping or reordering them (especially steps 5–7) is the most common source of errors.
Go to [developers.facebook.com](https://developers.facebook.com) → **My Apps** → **Create App**.
* App type: **Business**
* Add your Business Portfolio when prompted
* After creation, click **Add Product** → find **WhatsApp** → click **Set Up**
If you already have a Meta app with WhatsApp added, you can skip this step.
Just make sure it is in **Live** mode (not Development) before going to production.
During the WhatsApp product setup in your app, Meta will prompt you to select or create a
WhatsApp Business Account. Either:
* **Create a new WABA** — follow the prompts to set up a new account, or
* **Connect an existing WABA** — select it from the dropdown if you already have one
Once connected, the WABA will appear in [Meta Business Settings](https://business.facebook.com/settings)
under **Accounts → WhatsApp Accounts**.
In [Meta Business Settings](https://business.facebook.com/settings):
**Accounts → WhatsApp Accounts → \[your WABA] → Settings tab**
Copy the **Account ID** — it is a 15-digit numeric string. This is your **WABA ID**.
Do not enter the WABA *name* (e.g. "My Business"). You need the numeric Account ID.
It looks like `123456789012345`.
In [Meta Business Settings](https://business.facebook.com/settings):
**Accounts → WhatsApp Accounts → \[your WABA] → Phone Numbers tab**
Click on your phone number and copy the **Phone Number ID** — a 15-digit numeric string.
This is NOT the display phone number like `+1 555 123 4567`. It is the internal Meta ID
for that number, a long numeric string. Using the display number will cause `meta_graph_100` errors.
In [Meta Business Settings](https://business.facebook.com/settings):
**Users → System Users → Add**
* Role: **Admin**
* Name: something recognizable, e.g. `switchbord`
Click **Create System User**.
System User tokens are permanent (non-expiring) and are not tied to any individual person's account.
This is why they are strongly preferred over personal user tokens or page tokens for production integrations.
If the person who created a user token leaves the organization, the token stops working. System User tokens do not have this problem.
**This is the most commonly missed step.** Skipping it causes `meta_graph_190` (OAuthException)
even when your token is valid, has correct scopes, and has never expired.
The token is fine — the System User just isn't authorized for the WABA yet.
In [Meta Business Settings](https://business.facebook.com/settings):
**Accounts → WhatsApp Accounts → \[your WABA] → Settings tab → Assigned system users**
1. Click **Add people**
2. Select your System User (e.g. `switchbord`)
3. Set permission level to **Full control**
4. Click **Save**
You should now see your System User listed under assigned users for the WABA.
In [Meta Business Settings](https://business.facebook.com/settings):
**Users → System Users → \[your system user] → Generate new token**
* Select your Meta App (the one you created in Step 1)
* Grant these scopes:
* `whatsapp_business_messaging`
* `whatsapp_business_management`
* Set token expiry to **Never**
* Click **Generate Token** and copy the full token immediately
You only get to see this token once. Copy it to a secure password manager before closing the dialog.
If you lose it, you will need to generate a new one.
Generate the token *after* assigning the System User to the WABA (Step 6). Some users generate
the token first and then assign — the token itself does not pick up the new WABA access automatically
in all cases. When in doubt, generate a fresh token after assigning.
Go to [developers.facebook.com](https://developers.facebook.com) → **My Apps** → your app →
**Settings → Basic → App Secret → Show**.
Copy the App Secret. You will need it for webhook signature validation in Switchbord.
In Switchbord, open **Settings → Channel**:
* **Phone Number ID**: paste the 15-digit numeric ID from Step 4
* **WABA ID**: paste the 15-digit numeric ID from Step 3
Save the channel settings.
In Switchbord, open **Settings → Provider**:
* **Meta access token**: paste the System User token from Step 7
* **Meta App Secret**: paste the App Secret from Step 8
* **Verify Token**: click **Generate** to create a random verify token (or enter your own)
Save the provider settings. Copy the generated Verify Token — you will need it in the next step.
Go to [developers.facebook.com](https://developers.facebook.com) → **My Apps** → your app →
**WhatsApp → Configuration → Webhook**.
* **Callback URL**: `https://api.switchbord.ai/webhooks/meta`
* **Verify Token**: paste the exact value from Switchbord Settings → Provider
Click **Verify and Save**. Meta will make a challenge request to the webhook URL to confirm it responds correctly.
If webhook verification fails, the most likely causes are:
1. The WABA is not yet connected (go back and complete Steps 3–6)
2. The Verify Token does not match exactly (check for leading/trailing spaces)
3. The callback URL has a typo
After verifying the webhook, click **Manage** next to webhook subscriptions and enable at minimum:
* `messages`
* `message_deliveries`
* `messaging_optins`
Click **Done**.
In Switchbord, open **Settings** and run **Validate configuration**.
All indicators should turn green. If any are red, see the Troubleshooting section below.
Send a test message to your WhatsApp number from a personal phone to confirm end-to-end delivery
before moving to production traffic.
***
## Troubleshooting — Error Codes
| Error | Meaning | Fix |
| -------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `meta_graph_190` | OAuthException — System User not assigned to WABA, or token expired | **Most likely:** assign the System User to the WABA (Step 6 above). If already assigned, check the token hasn't expired. If using a User token instead of a System User token, generate a proper System User token. |
| `meta_graph_100` | Invalid Phone Number ID | Your Phone Number ID in Settings → Channel is wrong or still a placeholder. Get the real 15-digit numeric ID from Meta Business Settings → Phone Numbers tab. Do not use the display number (+1 555...). |
| Webhook callback failure `#N/A:WBxP...` | Meta cannot complete the verify handshake | Check: (1) webhook URL is exactly `https://api.switchbord.ai/webhooks/meta` with no trailing slash; (2) the verify token in Meta matches exactly what is saved in Switchbord — no extra spaces; (3) the WABA must be connected before subscribing the webhook. |
| `workspace_secret_store_unavailable` | `SUPABASE_DB_URL` is missing from Vercel environment | Contact your Switchbord administrator — this is an infrastructure configuration issue, not a Meta credential issue. |
| Token works in Meta API Explorer but fails in Switchbord | Token type mismatch | The API Explorer uses a temporary User token. Switchbord requires a permanent System User token. Generate a System User token with the steps above. |
***
## Common Mistakes
Even experienced operators hit these. Do not feel bad — the Meta Business Suite UI makes all of them easy to do by accident.
* **Entering the display phone number** (+1 555 123 4567) instead of the Phone Number ID (15-digit numeric). These look completely different; the ID does not contain country code formatting.
* **Entering the WABA name** instead of the WABA Account ID. The name is a human label; the ID is the numeric string.
* **Generating the System User token before assigning it to the WABA.** Always assign first, then generate. If you did it in the wrong order, generate a fresh token after assigning.
* **Using a User token or Page token** instead of a permanent System User token. User tokens expire or break when the user's account changes. System User tokens are persistent.
* **Leaving the Meta app in Development mode.** In Development mode, only test numbers can send/receive messages. Switch the app to **Live** mode for production use.
* **Verify token mismatch from copy-paste.** A trailing space or newline in the verify token will cause webhook verification to fail silently. Use the copy button in Switchbord rather than selecting text manually.
***
## What Switchbord Will Not Show You
For security, Switchbord does not echo stored secret values back to the browser.
You will only see:
* Configured or missing state
* Whether the value came from Vault or environment fallback
* Masked hints where available
* Last validation status and error code
***
## Ongoing Maintenance
After go-live:
* Rotate tokens from Settings instead of redeploying the app
* Re-run validation after rotation
* Keep environment values only as bootstrap or emergency fallback
* System User tokens set to Never expire do not need rotation on a schedule, but rotate them if you suspect compromise
***
## Read Next
* [Meta Credential Setup — Operator Guide](/operations/meta-credential-setup)
* [Operator Onboarding](/platform/onboarding)
* [Platform Architecture](/platform/architecture)
* [Internal API](/api-reference/introduction)