Skip to main content

​
Meta WhatsApp Credential Setup

This guide is for operators and platform administrators setting up Meta WhatsApp Business API credentials for a Switchbord workspace. It covers all credential types, explains why each is needed, and walks through the exact Meta Business Suite navigation paths.
This guide covers the operator side of credential setup — what you do in Meta. For the Switchbord side (entering credentials in Settings), see Connect WhatsApp.

​
Why System User Tokens

Switchbord requires a System User access token rather than a personal User token or Page token. Here is why this matters: The critical advantage of System User tokens: they are not tied to any individual person’s account. If the person who created a User token leaves the organization, the token becomes invalid and your WhatsApp integration breaks — often silently, only discovered when messages stop sending. System User tokens also support setting expiry to Never, which eliminates the operational overhead of token rotation on a schedule.

​
Prerequisites

Before starting, confirm you have:
  • Admin access to a Meta Business Portfolio at business.facebook.com
  • A WhatsApp Business Account (WABA) already created or claimed
  • A verified business phone number in that WABA
  • A Meta App (type: Business) with the WhatsApp product added
If you do not have these, complete the Connect WhatsApp guide first — it walks through the full setup from scratch.

​
Step-by-Step Credential Setup

1

Access Meta Business Settings

Go to business.facebook.com/settings.All credential setup happens from this central panel. Bookmark it — you will return here often.
If you manage multiple Business Portfolios, confirm you are in the correct one by checking the portfolio name in the top-left dropdown.
2

Locate your WABA ID

Navigate to: Accounts → WhatsApp AccountsFind your WABA in the list and click on it. In the Settings tab, copy the Account ID.This is a 15-digit numeric string — your WABA ID. Save it somewhere accessible; you will need it when configuring Switchbord Settings → Channel.
3

Locate your Phone Number ID

Navigate to: Accounts → WhatsApp Accounts → [your WABA] → Phone Numbers tabClick on your phone number. Copy the Phone Number ID — again, a 15-digit numeric string.
The Phone Number ID is not the formatted phone number like +1 555 123 4567. It is a numeric internal ID that looks like 123456789012345. Using the formatted number will cause meta_graph_100 errors in Switchbord.
4

Create a System User

Navigate to: Users → System Users → AddConfigure:
  • Name: Choose something descriptive, e.g. switchbord-prod or switchbord-[workspace-name]
  • Role: Admin
Click Create System User.
You can create multiple System Users for different environments (staging, production) or different workspaces. Each System User can have its own token with its own scope set.
5

Assign the System User to your WABA

Do not skip this step. This is the single most common cause of meta_graph_190 (OAuthException) errors. The error message says “token invalid” but the token is fine — the System User simply does not have permission to act on the WABA.Even a valid, permanent, correctly-scoped System User token will return meta_graph_190 until the System User is assigned to the WABA.
Navigate to: Accounts → WhatsApp Accounts → [your WABA] → Settings tabScroll to Assigned system users and click Add people.
  1. Search for and select your System User by name
  2. Set permission to Full control
  3. Click Save
Confirm the System User now appears in the assigned users list.Why full control? Switchbord needs to send messages (write), read delivery receipts (read), and manage webhook subscriptions (admin). Partial permissions will cause intermittent failures.
6

Generate the System User access token

Navigate to: Users → System Users → [your System User] → Generate new tokenIn the token generation dialog:
  1. Select app: choose your Meta App (App ID: 1485717133228319 for Switchbord’s app)
  2. Select permissions — grant at minimum:
    • whatsapp_business_messaging — required for sending messages
    • whatsapp_business_management — required for WABA management, phone number queries, and WABA billing analytics
    • ads_read — required for Meta campaign/ad lookup in Insights
    • read_insights — required for Meta WABA pricing/billing analytics
    • paid_marketing_messages — required for paid marketing message analytics where applicable
  3. Token expiry: set to Never
  4. Click Generate Token
Copy the full token string immediately and store it in a secure credential manager.
This is the only time Meta shows you the full token. Once you close this dialog, you cannot retrieve it — only generate a new one (which invalidates the old one). Copy it now.
Generate the token after completing the WABA assignment in the previous step. Token generation does not retroactively pick up new WABA assignments in all cases. If you already generated a token before assigning, generate a fresh one now.
7

Retrieve the App Secret

Go to developers.facebook.com → My Apps → your app → Settings → Basic.Click Show next to the App Secret field. Copy the secret.Switchbord uses this to validate the HMAC signature on incoming webhook payloads from Meta, ensuring that messages cannot be spoofed by third parties.
The App Secret is different from the System User token. The token authenticates outbound API calls; the App Secret validates inbound webhook signatures. Both are required.
8

Configure the Meta webhook

In developers.facebook.com → My Apps → your app → WhatsApp → Configuration → Webhook:
  • Callback URL: https://api.switchbord.ai/webhooks/meta
  • Verify Token: copy from Switchbord Settings → Provider → Verify Token field
Click Verify and Save.Meta will immediately make a GET request to the callback URL with a challenge parameter. Switchbord responds with the challenge to confirm the endpoint is live and the verify token matches.
Webhook verification will fail if:
  • The WABA is not connected to the Meta app yet
  • The verify token in Meta does not exactly match the one saved in Switchbord
  • There is a trailing space or newline in either token value
After verification succeeds, click Manage and subscribe to these webhook fields:
  • messages — inbound messages and status updates
  • message_deliveries — delivery receipts
  • messaging_optins — opt-in events

​
Credential Reference

​
Token Security Practices

  • Store tokens in a team password manager (1Password, Bitwarden, etc.) not in personal vaults
  • Restrict token scopes to only whatsapp_business_messaging and whatsapp_business_management — do not grant broad permissions
  • Rotate tokens if compromised — generate a new System User token and update Switchbord Settings immediately
  • Never log or expose tokens in application logs, error messages, or version control
  • Use one System User per environment — separate tokens for staging and production simplify rotation and reduce blast radius

​
Configure Meta Marketing API in Switchbord

After the token exists in Meta, enter the Marketing API configuration in Switchbord:
  1. Open Settings → Integrations → Channels → WhatsApp.
  2. In Provider credentials, find the Meta Ads / Marketing API card.
  3. Choose one of:
    • Reuse WhatsApp token if your workspace’s existing WhatsApp token already has ads_read, read_insights, and whatsapp_business_management; or
    • Paste a separate System User token into Meta Ads token.
  4. Enter the Meta ad account id in the format act_1234567890.
  5. Click Save & validate.
For GB Viaggi, the current workspace WhatsApp token already has the required scopes. Use Reuse WhatsApp token and the ad account id act_474265269673453.
This configuration unlocks:
  • Insights → Meta ads campaign/ad comparison.
  • Insights → Billing WABA pricing_analytics and analytics ingestion.
  • Click-to-WhatsApp ad, ad set, and campaign enrichment when inbound referrals include an ad id.

​
Troubleshooting

See the full error code table in the Connect WhatsApp guide. Quick reference for the most common issues: meta_graph_190 after entering a valid token The System User is not assigned to the WABA. Complete Step 5 above. Webhook verification fails immediately Either the WABA is not connected to the Meta app, or the verify tokens do not match exactly. Copy the verify token using the copy button in Switchbord to avoid whitespace issues. Messages send but no delivery receipts arrive The message_deliveries webhook field is not subscribed. Go to WhatsApp → Configuration → Manage → enable message_deliveries.