From b4b7d1384323ff22fc2661df0b244858fec59c4e Mon Sep 17 00:00:00 2001 From: VirusDumb Date: Thu, 4 Jun 2026 20:53:41 +0530 Subject: [PATCH 1/3] Revise WhatsApp setup docs for Cloud API Rewrite the WhatsApp interface setup to target the WhatsApp Cloud API: remove the extra dependency note, clarify prerequisites (Business Portfolio, ngrok/cloudflared), and reorganize steps. Added explicit guidance for creating a Meta Business Account and app, obtaining Phone Number ID, Access Token and App Secret, and setting environment variables (including OPENAI_API_KEY). Updated server/tunnel instructions, webhook configuration, and subscription steps; added registration curl calls to activate test numbers. Introduced Signature Validation, Production Access, and a Troubleshooting table, and adjusted the development warning to include cloudflared. --- agent-os/interfaces/whatsapp/setup.mdx | 203 ++++++++++++++++--------- 1 file changed, 128 insertions(+), 75 deletions(-) diff --git a/agent-os/interfaces/whatsapp/setup.mdx b/agent-os/interfaces/whatsapp/setup.mdx index f3bbd257a..054799a75 100644 --- a/agent-os/interfaces/whatsapp/setup.mdx +++ b/agent-os/interfaces/whatsapp/setup.mdx @@ -1,113 +1,166 @@ --- title: Setup sidebarTitle: Setup -description: Configure Meta Developer account, WhatsApp Business API, and webhooks for WhatsApp bots. -keywords: [whatsapp, setup, meta, webhook, configuration, access token] +description: Configure a Meta app, WhatsApp Cloud API credentials, and webhooks for WhatsApp bots. +keywords: [whatsapp, setup, meta, webhook, configuration, access token, cloud api] --- - -Install the WhatsApp dependencies: `uv pip install 'agno[whatsapp]'` - +The WhatsApp interface uses the WhatsApp Cloud API. The `httpx` dependency it needs ships with Agno, so no extra install is required. -Ensure you have the following: - A [Meta Developer Account](https://developers.facebook.com/) -- A Meta Business Account (created at [Meta Business Manager](https://business.facebook.com/)) -- A valid Facebook account -- ngrok (for development) +- A [Meta Business Portfolio](https://business.facebook.com/) (Business Account) +- ngrok or cloudflared (to expose your local server) - Python 3.9+ + +1. Go to [Meta Business Manager](https://business.facebook.com/) and create a Business Portfolio. +2. Complete business verification to unlock production messaging limits and API access. + +Unverified accounts can still message test numbers but are capped at 250 business-initiated conversations per 24 hours. + + -1. Go to [Meta for Developers](https://developers.facebook.com/) and verify your account. -2. Create a new app at the [Apps Dashboard](https://developers.facebook.com/apps/). -3. Under "Use Case", select **Other**. -4. Choose **Business** as the app type. -5. Provide: - - App name - - Contact email -6. Click "Create App". -7. In the app dashboard, find **WhatsApp** in the product list and click **Set up** to add it. +1. Open the [Apps Dashboard](https://developers.facebook.com/apps/) and click **Create app**. +2. Under **App details**, give it a name and continue. +3. Under **Use cases**, select **Connect with customers through WhatsApp**, then click **Next**. +4. Under **Business**, link the app to the Business Portfolio from the previous step, then finish the **Requirements** and **Overview** steps to create the app. +5. On the app dashboard, click **Customize the Connect with customers through WhatsApp use case** (or open **Use cases** in the sidebar) to set up WhatsApp. This creates your WhatsApp Business Account (WABA). - -1. Navigate to [Meta Business Manager](https://business.facebook.com/). -2. Create a new business account or use an existing one. -3. Verify your business email. -4. In your Meta App, go to **App Settings > Basic** and click "Start Verification" under Business Verification. Complete this for production access. -5. Associate the app with your business account. + +In the **Connect with customers through WhatsApp** use case, go to **Basic setup > Step 1. Try it out**. Copy each value and set it as an environment variable: + +1. Meta claims a **WhatsApp test number** under **Test number**. Copy the **Phone Number ID** shown next to it: + ```bash + export WHATSAPP_PHONE_NUMBER_ID="123456789" + ``` +2. Under **Access token**, click **Generate token** and copy it. This temporary token expires after ~24 hours and is for development only: + ```bash + export WHATSAPP_ACCESS_TOKEN="EAAW..." + ``` + + +The test number can message any recipient you register on the **Step 1. Try it out** page. Adding and verifying your own business number with a permanent token is only required for production. See [Add a Phone Number](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/add-a-phone-number). + - -1. In your app dashboard, go to **WhatsApp > API Setup**. -2. Generate a **Temporary Access Token**. This token expires in ~24 hours and is suitable for development only. -3. Copy your **Phone Number ID**, shown below the test phone number. -4. Add a test recipient under the **To** field (your personal number for testing). - -For production, create a permanent token: -1. Go to [Meta Business Manager](https://business.facebook.com/) > **Business Settings > System Users**. -2. Click **Add** and create a new admin-level system user. -3. Click on the system user, then **Assign Assets**. -4. Assign your app with **Full control**. -5. Assign your WhatsApp Business Account with **Full control**. -6. Click **Generate Token** and select `whatsapp_business_messaging` and `whatsapp_business_management` permissions. -7. Copy and store the token securely. This token does not expire unless revoked. + +1. In the side menu, open **App settings > Basic**. +2. Copy the **App Secret**. It is used for webhook signature verification: + ```bash + export WHATSAPP_APP_SECRET="..." + ``` - -Create a `.env` file or export these variables: + ```bash -export WHATSAPP_ACCESS_TOKEN="your_access_token" -export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id" -export WHATSAPP_VERIFY_TOKEN="your_chosen_verify_token" # Any string you create +export WHATSAPP_VERIFY_TOKEN="my-verify-token" # Any string you choose (must match webhook config) +export OPENAI_API_KEY="sk-..." # Or whichever model provider you use ``` - -Find these values in your Meta App: -- **Access Token**: WhatsApp > API Setup (temporary) or System User token (permanent) -- **Phone Number ID**: WhatsApp > API Setup, below the test phone number -- **Verify Token**: A string you choose. Must match in both your app and Meta's webhook config. - -1. Run ngrok to expose your local server, ensuring the port matches your app (7777): + +Webhook verification requires your AgentOS server to be running and publicly reachable. Start it **before** configuring the webhook in Meta. + +1. With the env vars set, run any WhatsApp example: + ```bash + python whatsapp_bot.py + ``` +2. Expose it publicly with ngrok or any tunnel of your choice: ```bash ngrok http 7777 + # or: cloudflared tunnel --url http://localhost:7777 ``` -2. Copy the `https://` URL provided by ngrok. -3. In your Meta App, go to **WhatsApp > Configuration** and click "Edit" on the Webhook section. -4. Configure the webhook: - - **Callback URL**: `https:///whatsapp/webhook` - - **Verify Token**: The same value as your `WHATSAPP_VERIFY_TOKEN` -5. Click "Verify and save". Your Agno app must be running locally for verification to succeed. -6. After verification, click "Manage" next to Webhook fields. Subscribe to the **messages** field under `whatsapp_business_account`. + +Your webhook callback URL is `{your-public-domain}/whatsapp/webhook`. - -For **development**, skip signature validation: -```bash -export WHATSAPP_SKIP_SIGNATURE_VALIDATION="true" -``` + +1. In the use case, go to **Basic setup > Step 2. Production setup > Configure Webhooks**. +2. Set **Callback URL** to your public domain plus `/whatsapp/webhook`: + ``` + https://your-public-domain/whatsapp/webhook + ``` +3. Set **Verify Token** to the same string as your `WHATSAPP_VERIFY_TOKEN`. +4. Click **Verify and save**. Meta sends a GET challenge to your running server, which Agno verifies automatically. -For **production**, set your App Secret to enable webhook signature validation: -```bash -export WHATSAPP_APP_SECRET="your_meta_app_secret" -``` -Find the App Secret at **App Settings > Basic** in your Meta App dashboard. +See [Set Up Webhooks](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks) for the verification handshake and payload format. + + + +After verification, Meta usually opens the **Webhook fields** list and auto-subscribes the standard fields. Confirm the **messages** field shows **Subscribed**, or your server never receives incoming messages even though verification succeeded. + +To subscribe manually: +1. Open **Use cases > Connect with customers through WhatsApp > Customize**. +2. Go to **Basic setup > Step 2. Production setup** and scroll to **Webhook fields**. +3. Toggle the fields to **Subscribed**. **messages** is required; **message_template_status_update** and **history** are commonly enabled too. - -1. Start your app: `python whatsapp_bot.py` -2. Ensure ngrok is running and the webhook is verified. -3. Open WhatsApp and send a message to the test phone number. -4. The bot should respond in the same chat. -5. Send `/new` to start a fresh session (requires `db` on the agent). -6. Send an image or document to test media handling. + +Send a message to the test number from a recipient on your **Step 1. Try it out** allow-list. If your server receives the webhook and the agent replies, setup is complete. + +If no webhook requests arrive at your tunnel, the test number must be programmatically activated even though the dashboard shows it as "Active". Meta returns `200 OK` with a `message_id` but silently drops messages during routing until the number is registered. Run both calls with your access token: + +1. **Register the number** (provisions your `phone_number_id` on WhatsApp servers): + ```bash + curl -X POST "https://graph.facebook.com/v25.0/$WHATSAPP_PHONE_NUMBER_ID/register" \ + -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"messaging_product": "whatsapp", "pin": "123456"}' + ``` +2. **Subscribe the app to your WABA** (links your app to the Business Account): + ```bash + curl -X POST "https://graph.facebook.com/v25.0//subscribed_apps" \ + -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN" + ``` + Replace `` with your WhatsApp Business Account ID (shown under **Step 1. Try it out**). This call sends no body. + +After running both, message the test number again. Webhooks should now arrive. +## Signature Validation + +The webhook validates incoming requests with HMAC-SHA256 over the `X-Hub-Signature-256` header. If `WHATSAPP_APP_SECRET` is not set, the server returns `500` to fail securely. + +For **development**, skip validation: +```bash +export WHATSAPP_SKIP_SIGNATURE_VALIDATION="true" +``` + +For **production**, keep validation on and set the App Secret from **App settings > Basic**. Never enable the skip flag in production. + +## Production Access + +Once it works, keep developing with the temporary token and test number, or move toward production by adding and verifying your own business number and generating a permanent token. + +To create a permanent token: +1. Go to [Meta Business Settings](https://business.facebook.com/settings) > **System Users**. +2. Add an admin-level system user. +3. Assign your app and WhatsApp Business Account with **Full control**. +4. Click **Generate Token** and select `whatsapp_business_messaging` and `whatsapp_business_management`. +5. Store the token securely. It does not expire unless revoked. + +## Troubleshooting + +| Symptom | Cause | Fix | +|---------|-------|-----| +| Bot doesn't respond | Webhook not configured or server not running | Confirm the webhook shows "Verified" in Meta and your server is running | +| 401 Unauthorized | Token expired | Regenerate the temporary token or use a System User token | +| Webhook verification fails | Verify token mismatch | `WHATSAPP_VERIFY_TOKEN` must match the Meta config exactly | +| 500 on every webhook | `WHATSAPP_APP_SECRET` not set | Set the App Secret or enable the skip flag for development | +| Signature validation fails | Wrong app secret | Confirm `WHATSAPP_APP_SECRET` matches App settings > Basic | +| Messages not arriving | Not subscribed to events | Subscribe to the **messages** field in the webhook config (step 9) | +| Outbound returns 200 but nothing delivered / no webhooks | Test number not registered | Run the `/register` and `/subscribed_apps` calls (step 10) | +| SSL certificate errors (macOS) | Missing cert bundle | `export SSL_CERT_FILE=$(python3 -c "import certifi; print(certifi.where())")` | +| Non-PDF documents fail | API limitation | Only PDF documents are supported for input | +| Can only message test numbers | Not in production mode | Complete business verification and request production access | + -ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). +ngrok and cloudflared are for local development only. For production, see the [deployment templates](/deploy/templates). From 2bc8d9160f711d09019c719461f33e852d8bb578 Mon Sep 17 00:00:00 2001 From: VirusDumb Date: Thu, 4 Jun 2026 21:07:25 +0530 Subject: [PATCH 2/3] Clarify WhatsApp production setup steps Replace the previous brief instructions with step-by-step guidance for production setup via Basic setup > Step 2. Production setup. Adds instructions to register and verify business numbers, generate a permanent (non-expiring) token from the "Generate permanent token" task, and set WHATSAPP_ACCESS_TOKEN and WHATSAPP_PHONE_NUMBER_ID. Includes notes on adding payment for business-initiated messages, warns not to confuse the permanent token generation task with the sidebar "Step 1. Try it out" (temporary token), and calls out that the older Business Settings > System Users token flow is no longer valid for WhatsApp. --- agent-os/interfaces/whatsapp/setup.mdx | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/agent-os/interfaces/whatsapp/setup.mdx b/agent-os/interfaces/whatsapp/setup.mdx index 054799a75..c009dc69e 100644 --- a/agent-os/interfaces/whatsapp/setup.mdx +++ b/agent-os/interfaces/whatsapp/setup.mdx @@ -137,14 +137,21 @@ For **production**, keep validation on and set the App Secret from **App setting ## Production Access -Once it works, keep developing with the temporary token and test number, or move toward production by adding and verifying your own business number and generating a permanent token. - -To create a permanent token: -1. Go to [Meta Business Settings](https://business.facebook.com/settings) > **System Users**. -2. Add an admin-level system user. -3. Assign your app and WhatsApp Business Account with **Full control**. -4. Click **Generate Token** and select `whatsapp_business_messaging` and `whatsapp_business_management`. -5. Store the token securely. It does not expire unless revoked. +Once it works, keep developing with the temporary token and test number, or move toward production by adding your own business number and generating a permanent token. Both are done from **Basic setup > Step 2. Production setup** (not **Step 1. Try it out**, which only provides the temporary token and test number). + +1. **Add your number.** Under **Register your WhatsApp phone number**, click **Add new number** and verify it. You can add up to 2 numbers before business verification, and up to 20 after. Manage numbers anytime in [WhatsApp Manager](https://business.facebook.com/wa/manage/). +2. **Generate a permanent token.** Still on **Step 2. Production setup**, scroll to **Test your registered number** and use **Step 1: Generate permanent token** to generate the token for your WhatsApp Business Account, then copy it. Unlike the temporary token, it does not expire. + + +Do not confuse this **Step 1: Generate permanent token** task (inside **Step 2. Production setup > Test your registered number**) with the **Step 1. Try it out** entry in the sidebar. The sidebar's **Step 1. Try it out** only provides the temporary token and test number. + + +3. Set the permanent token as your `WHATSAPP_ACCESS_TOKEN`, and update `WHATSAPP_PHONE_NUMBER_ID` to your registered number's ID. +4. To send business-initiated messages (marketing, utility, authentication), complete **Add payment** in the same step. Replies to user-initiated messages are free for the first 1,000 conversations per month. + + +The older **Business Settings > System Users** token flow now shows "No permissions available" for the WhatsApp use case. Use **Step 2. Production setup** instead. + ## Troubleshooting From 03842c7419ab6c4d94ac3c7ee334f3a9fa70c2fd Mon Sep 17 00:00:00 2001 From: VirusDumb Date: Thu, 4 Jun 2026 21:36:08 +0530 Subject: [PATCH 3/3] cook book fix --- agent-os/interfaces/whatsapp/setup.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/agent-os/interfaces/whatsapp/setup.mdx b/agent-os/interfaces/whatsapp/setup.mdx index c009dc69e..6c28dfaaa 100644 --- a/agent-os/interfaces/whatsapp/setup.mdx +++ b/agent-os/interfaces/whatsapp/setup.mdx @@ -1,11 +1,11 @@ --- title: Setup sidebarTitle: Setup -description: Configure a Meta app, WhatsApp Cloud API credentials, and webhooks for WhatsApp bots. -keywords: [whatsapp, setup, meta, webhook, configuration, access token, cloud api] +description: Configure a Meta app, credentials, and webhooks for WhatsApp bots. +keywords: [whatsapp, setup, meta, webhook, configuration, access token] --- -The WhatsApp interface uses the WhatsApp Cloud API. The `httpx` dependency it needs ships with Agno, so no extra install is required. +Connect any Agno agent, team, or workflow to WhatsApp. The `httpx` dependency the interface needs ships with Agno, so no extra install is required.