Skip to main content

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.

Connect a WhatsApp Business number to any Friday workspace so customers can chat with it over WhatsApp. Friday talks to the WhatsApp Business Cloud API, so you’ll create an app at developers.facebook.com.
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.

​
Prerequisites

  • A Meta developer account — 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

1

Create a Meta app

  1. Open developers.facebook.com/apps and click Create app.
  2. App details — pick an app name.
    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).
  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.
2

Create a permanent access token

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.
  1. Open 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.
3

Collect the other two values

NameWhere in the dashboard
Phone number IDWhatsApp → API Setup → Phone number ID
App SecretApp Settings → Basic → Show next to App Secret
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.
4

Connect WhatsApp in Studio

  1. Open Studio and pick your workspace.
  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.
5

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

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

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.

​
Troubleshooting

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.
app_secret doesn’t match the App Secret under App Settings → Basic. Re-copy and reconnect via Studio; any whitespace or truncation fails verification.
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.
Production requires registering a real business number with OTP verification — free test numbers are capped at 5 approved recipients and cannot be promoted.

​
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 ~/.atlas/.env). You’ll also need to set the callback URL and verify token in Meta’s dashboard manually.
workspace.yml
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
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.