Skip to main content

​
Meta credentials

Switchbord talks to the WhatsApp Business Platform through Meta’s Graph API. Before any message can flow, five things need to be in place:
  1. Meta access token (System User token)
  2. App Secret (webhook signing)
  3. Verify token (webhook handshake)
  4. Phone Number ID (which phone to send from)
  5. WhatsApp Business Account ID (WABA ID — the account that owns the phone)
You can paste all five from the Channel Settings page or the in-app welcome wizard at /welcome. Each field has a “Where do I find this?” toggle with the exact path in Meta Business Suite and a deep-link that jumps you straight there.

​
1 · Meta access token

  1. Open Meta Business Settings → Users → System Users.
  2. Select the System User assigned to your WABA (create one if you don’t have it — it must have Full control over the WABA).
  3. Click Generate new token, pick your WhatsApp app, and grant:
    • whatsapp_business_management
    • whatsapp_business_messaging
  4. Copy the long EAAG… string and paste it into Channel settings → Provider credentials → Meta Access Token.
Switchbord encrypts the token at rest in Supabase Vault. It never appears in application logs.

​
2 · App Secret

  1. Open Meta App Dashboard and pick your WhatsApp app.
  2. Navigate to App settings → Basic.
  3. Click Show next to App secret, authenticate, and copy the value.
  4. Paste it into Channel settings → Webhook Signing Secret.
The App Secret is how Switchbord verifies that inbound webhook payloads really came from Meta (HMAC-SHA256 over the raw body).

​
3 · Verify token

This one is yours to invent — Switchbord can generate it for you.
  1. In the welcome wizard step 3 (or Channel settings → Meta verify token), click Generate.
  2. Copy the generated swb_… token.
  3. In Meta App Dashboard → WhatsApp → Configuration → Webhooks, click Edit, paste the same token, and set the Callback URL to the one shown in the wizard.
Meta calls GET {callbackUrl}?hub.verify_token=… once — Switchbord replies with the matching challenge if the tokens agree.

​
4 · Phone Number ID

  1. Open WhatsApp Manager — Phone Numbers.
  2. Select the business that owns your WABA.
  3. Find the row for the WhatsApp number you want to send from.
  4. Copy the long numeric value in the ID column (typically 15 digits).
  5. Paste it into Channel settings → WhatsApp phone ID.
After you save, Switchbord calls GET https://graph.facebook.com/v25.0/{phone_number_id} to confirm the ID is real and belongs to the scope of your access token. You’ll see a green “Verified with Meta” line on success, or a red “Meta rejected this ID” line with the exact error code on failure (typically meta_graph_100 if the ID is wrong or meta_graph_190 if the token lacks access).

​
5 · WhatsApp Business Account ID (WABA ID)

  1. Open Business Settings → Accounts → WhatsApp Accounts.
  2. Select your WABA.
  3. The numeric ID is shown under the account name (and in the URL — business.facebook.com/settings/whatsapp-business-accounts/<WABA_ID>).
  4. Paste into Channel settings → WhatsApp Business Account ID.
The WABA ID is used to submit templates and read account-level metadata. Switchbord validates it against GET https://graph.facebook.com/v25.0/{waba_id} immediately after save.

​
Troubleshooting

​
Alternative: Meta Embedded Signup

The five steps above are the bring-your-own-token path — always available and the only path for self-hosted deployments. If your deployment has Embedded Signup enabled (NEXT_PUBLIC_EMBEDDED_SIGNUP_ENABLED=1 plus the Meta app credentials), /welcome also offers a Meta-hosted sign-in flow that skips steps 1, 4, and 5 above entirely — Meta returns the WABA ID and Phone Number ID directly, and Switchbord exchanges a one-time code for the access token server-side. It also transparently supports onboarding a second WABA into the same workspace without touching the first WABA’s stored token. See Meta Embedded Signup & Multi-WABA for the full flow.

​
Reference

  • packages/whatsapp/validate-meta-ids.ts — live-validates Phone Number ID and WABA ID against Meta’s Graph API.
  • apps/app/app/api/settings/meta/validate-ids/route.ts — the endpoint the UI calls.
  • Channel settings live on channels.phone_number_id and channels.waba_id (see packages/database/src/adapters/messages.ts).
  • apps/app/app/api/onboarding/meta/exchange/route.ts — the Embedded Signup code-exchange endpoint (see Meta Embedded Signup & Multi-WABA).