Skip to main content

​
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.
1

Create a Meta App

Go to 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.
2

Create or connect a WhatsApp Business Account (WABA)

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 under Accounts → WhatsApp Accounts.
3

Get your WABA ID

In Meta Business Settings:Accounts → WhatsApp Accounts → [your WABA] → Settings tabCopy 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.
4

Get your Phone Number ID

In Meta Business Settings:Accounts → WhatsApp Accounts → [your WABA] → Phone Numbers tabClick 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.
5

Create a System User

In Meta Business 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.
6

Assign the System User to your WABA

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: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.
7

Generate a System User access token

In Meta Business 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.
8

Get your App Secret

Go to 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.
9

Configure Switchbord — Channel settings

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.
10

Configure Switchbord — Provider credentials

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.
11

Configure the Meta webhook

Go to 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
12

Subscribe to webhook fields

After verifying the webhook, click Manage next to webhook subscriptions and enable at minimum:
  • messages
  • message_deliveries
  • messaging_optins
Click Done.
13

Validate configuration in Switchbord

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

​
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