> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hellofriday.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp

> Connect a WhatsApp Business number to a space for customer chat.

Connect a WhatsApp Business number to any Friday space so customers can chat with it over WhatsApp. Friday talks to the [WhatsApp Business Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api), so you'll create an app at [developers.facebook.com](https://developers.facebook.com/apps).

<Warning>
  **This is NOT WhatsApp Web.** `web.whatsapp.com` is the consumer client — bots
  can't be built on top of it. You need the *Business Cloud API*, which is a
  separate Meta developer product.
</Warning>

## Prerequisites

* A Meta developer account — [developers.facebook.com](https://developers.facebook.com)
* A Facebook Business Manager (free to create)
* A phone number you can receive SMS/calls on for OTP verification (for production). For dev, Meta gives you a **free test number** that can message up to 5 verified recipients.
* Friday running with the bundled tunnel active, or a real HTTPS domain.

## Setup

<Steps>
  <Step title="Create a Meta app">
    1. Open [developers.facebook.com/apps](https://developers.facebook.com/apps) and click **Create app**.
    2. **App details** — pick an app name.
           <Warning>
             Don't include the words `WhatsApp`, `FB`, `Face`, `Book`, `Insta`, `Gram`, or `Rift` — Meta's trademark filter rejects them silently (the Next button just stays disabled).
           </Warning>
    3. **Use cases** — choose **Other** → **Business** → then tick **Connect with customers through WhatsApp**.
    4. **Business portfolio** — select an existing Business portfolio or create a new one. Pick **Verify later** unless you already have the business paperwork ready.
    5. **Requirements → Overview → Create app.** Meta re-prompts for your Facebook password before finalizing.
    6. On the "Welcome to WhatsApp Business Platform" page, accept the **Facebook Terms for WhatsApp Business** and **Meta Hosting Terms** and click **Continue**.
    7. Keep the default **Opt in to all current and future WhatsApp accounts**, then **Continue** → **Save**.
  </Step>

  <Step title="Create a permanent access token">
    <Warning>
      The big green **Generate access token** button on **WhatsApp → API Setup** gives you a *temporary* token that stops working after 24 hours. Don't use it. The System User token below never expires.
    </Warning>

    1. Open [business.facebook.com/latest/settings/system\_users](https://business.facebook.com/latest/settings/system_users) and select the right business at the top-left.
    2. **Users** → **System users** → click **Add**.
    3. Fill in the form — name the system user (avoid hyphens), set role to **Admin**, then **Create system user**.
    4. Click **Assign assets** → pick **WhatsApp accounts** → check your WhatsApp Business Account → toggle **Everything** on → **Assign assets** → **Done**.
    5. **Accounts → Apps**, click your app, then **Assign people** → check the system user → toggle **Manage app** on (Full control) → **Assign**.
    6. Back on **System users → \<your system user>** click **Generate token**:
       * Select your Meta app → **Next**
       * Set expiration: **Never** → **Next**
       * Tick both `whatsapp_business_messaging` and `whatsapp_business_management` → **Generate token**
       * Copy the token immediately — the popup shows it once.
  </Step>

  <Step title="Collect the other two values">
    | Name            | Where in the dashboard                               |
    | --------------- | ---------------------------------------------------- |
    | Phone number ID | WhatsApp → API Setup → *Phone number ID*             |
    | App Secret      | App Settings → Basic → **Show** next to *App Secret* |

    <Tip>
      For **App Secret**, use the copy icon rather than retyping — hex fonts make `6c` look like `c`, and a single wrong character breaks signature verification.
    </Tip>
  </Step>

  <Step title="Connect WhatsApp in Studio">
    1. In Studio, select your space from the sidebar and click **Info**.
    2. Find the **Communicators** card and click **Connect** next to **WhatsApp**.
    3. Paste the **Access Token**, **App Secret**, and **Phone Number ID** into the form, then submit.

    Studio stores the credentials securely and registers the webhook with Meta for you. The status flips to **Connected** when it's done.
  </Step>

  <Step title="Subscribe to the messages webhook field">
    Meta requires you to opt in to the events you want to receive.

    1. In the Meta dashboard, left nav **Configuration** (under "Connect on WhatsApp" use case).
    2. In the **Webhook fields** table, find `messages` and toggle its **Subscribe** switch. Optionally also subscribe to `message_status` / `message_echoes`.
  </Step>

  <Step title="Add recipients (test number only)">
    If you're using Meta's free test number, WhatsApp will only deliver outbound messages to **pre-verified** recipients. Inbound is unrestricted.

    1. Left nav → **API Setup**.
    2. Click the **To** combobox → **Manage phone number list**.
    3. Type the 10-digit national number. Click **Next**. Meta sends a WhatsApp message to that number with a **5-digit verification code**.
    4. Enter the code into the verification modal.

    Production numbers (once registered and approved) can receive from anyone.
  </Step>

  <Step title="Talk to your bot">
    From a verified WhatsApp number on your phone, send a message to the business number. It should appear in Studio with a green **WHATSAPP** badge, and replies flow back automatically.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook fails to register from Studio">
    Usually a token issue. Make sure your access token has both `whatsapp_business_messaging` and `whatsapp_business_management` scopes, and that the system user has been assigned the WhatsApp Business Account.
  </Accordion>

  <Accordion title="Signature verification errors">
    `app_secret` doesn't match the App Secret under **App Settings → Basic**.
    Re-copy and reconnect via Studio; any whitespace or truncation fails
    verification.
  </Accordion>

  <Accordion title="Outbound replies fail with 'Access denied' (HTTP 403)">
    You're using the 24-hour *temporary* access token from **WhatsApp → API
    Setup** and it expired. Create a permanent System User token following the
    steps above and reconnect.
  </Accordion>

  <Accordion title="Test number recipient limit (5)">
    Production requires registering a real business number with OTP verification — free test numbers are capped at 5 approved recipients and cannot be promoted.
  </Accordion>
</AccordionGroup>

## Production notes

* Meta rotates App Secrets on request under **App Settings → Basic → Reset**. After rotating, reconnect WhatsApp in Studio so the new secret is stored.
* WhatsApp message history **cannot** be fetched via the Cloud API — only messages received while Friday is running are available as conversational context.
* You can't edit or delete already-sent WhatsApp messages. Streaming replies are sent as a single message once the response is complete.

## Configure via YAML

For CI or fully scripted setups, paste credentials directly into `workspace.yml` or the `.env` file in the Friday home directory (default `~/.friday/local/.env`). You'll also need to set the callback URL and verify token in Meta's dashboard manually.

<Tabs>
  <Tab title="Credentials inline">
    ```yaml workspace.yml theme={null}
    communicators:
      whatsapp:
        kind: whatsapp
        access_token: "EAA..."
        app_secret: "0ad6c116..."
        phone_number_id: "15551234567"
        verify_token: "<your-random-string>"
        api_version: "v21.0"  # optional; defaults to v21.0
    ```
  </Tab>

  <Tab title="Credentials via env">
    ```bash # Friday home .env (default ~/.friday/local/.env) theme={null}
    WHATSAPP_ACCESS_TOKEN=EAA...
    WHATSAPP_PHONE_NUMBER_ID=15551234567
    WHATSAPP_APP_SECRET=0ad6c116...
    WHATSAPP_VERIFY_TOKEN=<your-random-string>
    ```

    ```yaml workspace.yml theme={null}
    communicators:
      whatsapp:
        kind: whatsapp
    ```
  </Tab>
</Tabs>

Generate a verify token with `openssl rand -hex 32`. Then in the Meta dashboard's **Configuration** panel, paste the **Callback URL** as `<tunnel>/platform/whatsapp` and the **Verify token** you chose, click **Verify and save**, and subscribe to the `messages` field.