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

# Meta WhatsApp Credential Setup

> Detailed operational guide for setting up Meta WhatsApp Business API credentials — System User tokens, WABA assignment, webhook configuration, and security best practices.

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

<Note>
  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](/platform/connect-whatsapp).
</Note>

***

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

| Token Type               | Expiry                    | Tied To                           | Recommended For             |
| ------------------------ | ------------------------- | --------------------------------- | --------------------------- |
| User token (short-lived) | 1–2 hours                 | Individual person's login session | Testing only                |
| User token (long-lived)  | 60 days                   | Individual person's account       | Never for production        |
| Page token               | Varies                    | Facebook Page + individual person | Not applicable for WhatsApp |
| System User token        | Never (when set to Never) | Business Portfolio, not a person  | **Production — use this**   |

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](https://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](/platform/connect-whatsapp) guide first —
it walks through the full setup from scratch.

***

## Step-by-Step Credential Setup

<Steps>
  <Step title="Access Meta Business Settings">
    Go to [business.facebook.com/settings](https://business.facebook.com/settings).

    All credential setup happens from this central panel. Bookmark it — you will return here often.

    <Tip>
      If you manage multiple Business Portfolios, confirm you are in the correct one by checking
      the portfolio name in the top-left dropdown.
    </Tip>
  </Step>

  <Step title="Locate your WABA ID">
    Navigate to: **Accounts → WhatsApp Accounts**

    Find 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.
  </Step>

  <Step title="Locate your Phone Number ID">
    Navigate to: **Accounts → WhatsApp Accounts → \[your WABA] → Phone Numbers tab**

    Click on your phone number. Copy the **Phone Number ID** — again, a 15-digit numeric string.

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Create a System User">
    Navigate to: **Users → System Users → Add**

    Configure:

    * **Name**: Choose something descriptive, e.g. `switchbord-prod` or `switchbord-[workspace-name]`
    * **Role**: Admin

    Click **Create System User**.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Assign the System User to your WABA">
    <Warning>
      **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.
    </Warning>

    Navigate to: **Accounts → WhatsApp Accounts → \[your WABA] → Settings tab**

    Scroll 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.
  </Step>

  <Step title="Generate the System User access token">
    Navigate to: **Users → System Users → \[your System User] → Generate new token**

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

    <Warning>
      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.
    </Warning>

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="Retrieve the App Secret">
    Go to [developers.facebook.com](https://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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Configure the Meta webhook">
    In [developers.facebook.com](https://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.

    <Warning>
      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
    </Warning>

    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
  </Step>
</Steps>

***

## Credential Reference

| Credential               | Where to Find It                                                             | Where to Enter It in Switchbord                                                   |
| ------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| WABA ID                  | Business Settings → Accounts → WhatsApp Accounts → Settings tab → Account ID | Settings → Channel → WABA ID                                                      |
| Phone Number ID          | Business Settings → WhatsApp Accounts → \[WABA] → Phone Numbers → \[number]  | Settings → Channel → Phone Number ID                                              |
| System User access token | Business Settings → Users → System Users → Generate new token                | Settings → Provider → Meta access token                                           |
| App Secret               | developers.facebook.com → App → Settings → Basic → App Secret                | Settings → Provider → Meta App Secret                                             |
| Verify Token             | Generated in Switchbord Settings → Provider                                  | developers.facebook.com → App → WhatsApp → Configuration → Webhook → Verify Token |

***

## 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**.

<Info>
  For GB Viaggi, the current workspace WhatsApp token already has the required scopes. Use **Reuse WhatsApp token** and the ad account id `act_474265269673453`.
</Info>

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](/platform/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`.

***

## Related Guides

* [Connect WhatsApp — Full Setup Walkthrough](/platform/connect-whatsapp)
* [Webhooks](/operations/webhooks)
* [Secrets and Encryption](/security/secrets-and-encryption)
* [Operator Onboarding](/platform/onboarding)