From db0b36c26f4200c8d88f09733c7ce404a6e75904 Mon Sep 17 00:00:00 2001 From: Mustafa Esoofally Date: Tue, 2 Jun 2026 14:28:44 -0400 Subject: [PATCH 1/9] fix: restore interface setup docs and break circular references The Slack, Telegram, and WhatsApp interface docs had circular references: - /agent-os/.../introduction linked to /deploy/.../overview for setup - /deploy/.../overview linked back to /agent-os/.../introduction for setup - Neither page had the actual setup steps (deleted in PR #644) This commit: - Creates dedicated setup.mdx pages under /deploy/interfaces/{slack,telegram,whatsapp}/ - Restores the full setup content that was deleted (BotFather, Meta App, Slack App setup steps) - Updates both introduction and overview pages to link to the new setup pages - Updates docs.json navigation to show nested Setup pages under each interface --- agent-os/interfaces/slack/introduction.mdx | 2 +- agent-os/interfaces/telegram/introduction.mdx | 2 +- agent-os/interfaces/whatsapp/introduction.mdx | 2 +- deploy/interfaces/slack/overview.mdx | 2 +- deploy/interfaces/slack/setup.mdx | 190 ++++++++++++++++++ deploy/interfaces/telegram/overview.mdx | 2 +- deploy/interfaces/telegram/setup.mdx | 166 +++++++++++++++ deploy/interfaces/whatsapp/overview.mdx | 2 +- deploy/interfaces/whatsapp/setup.mdx | 145 +++++++++++++ docs.json | 24 ++- 10 files changed, 528 insertions(+), 9 deletions(-) create mode 100644 deploy/interfaces/slack/setup.mdx create mode 100644 deploy/interfaces/telegram/setup.mdx create mode 100644 deploy/interfaces/whatsapp/setup.mdx diff --git a/agent-os/interfaces/slack/introduction.mdx b/agent-os/interfaces/slack/introduction.mdx index e13133b9a..d5cd67ea0 100644 --- a/agent-os/interfaces/slack/introduction.mdx +++ b/agent-os/interfaces/slack/introduction.mdx @@ -9,7 +9,7 @@ The Slack interface lets you deploy agents, teams, or workflows as interactive S ## Setup -Follow the [Slack deploy guide](/deploy/interfaces/slack/overview) to create a Slack App and configure OAuth scopes, event subscriptions, and App Home. +Follow the [Slack setup guide](/deploy/interfaces/slack/setup) to create a Slack App and configure OAuth scopes, event subscriptions, and App Home. Install the Slack dependencies: `uv pip install 'agno[slack]'` diff --git a/agent-os/interfaces/telegram/introduction.mdx b/agent-os/interfaces/telegram/introduction.mdx index 38bdfffe3..d1da0db1f 100644 --- a/agent-os/interfaces/telegram/introduction.mdx +++ b/agent-os/interfaces/telegram/introduction.mdx @@ -9,7 +9,7 @@ The Telegram interface exposes an Agno Agent, Team, or Workflow on Telegram via ## Setup -Follow the [Telegram deploy guide](/deploy/interfaces/telegram/overview) to set up your bot. +Follow the [Telegram setup guide](/deploy/interfaces/telegram/setup) to set up your bot. Required configuration: diff --git a/agent-os/interfaces/whatsapp/introduction.mdx b/agent-os/interfaces/whatsapp/introduction.mdx index c0c83ab20..d21c44e32 100644 --- a/agent-os/interfaces/whatsapp/introduction.mdx +++ b/agent-os/interfaces/whatsapp/introduction.mdx @@ -9,7 +9,7 @@ The WhatsApp interface lets you deploy agents, teams, or workflows as WhatsApp b ## Setup -Follow the [WhatsApp deploy guide](/deploy/interfaces/whatsapp/overview) to create a Meta App, configure the WhatsApp Business API, and set up webhooks. +Follow the [WhatsApp setup guide](/deploy/interfaces/whatsapp/setup) to create a Meta App, configure the WhatsApp Business API, and set up webhooks. Required configuration: diff --git a/deploy/interfaces/slack/overview.mdx b/deploy/interfaces/slack/overview.mdx index 5ee171be2..a789e61b7 100644 --- a/deploy/interfaces/slack/overview.mdx +++ b/deploy/interfaces/slack/overview.mdx @@ -40,7 +40,7 @@ python -m agno.os.serve slack_agent:app --port 7777 ## Setup -Requires a Slack App with OAuth scopes and event subscriptions. See the [full setup guide](/agent-os/interfaces/slack/introduction#setup) for step-by-step instructions. +Requires a Slack App with OAuth scopes and event subscriptions. See the [setup guide](/deploy/interfaces/slack/setup) for step-by-step instructions. **Environment variables:** ```bash diff --git a/deploy/interfaces/slack/setup.mdx b/deploy/interfaces/slack/setup.mdx new file mode 100644 index 000000000..f60f8d100 --- /dev/null +++ b/deploy/interfaces/slack/setup.mdx @@ -0,0 +1,190 @@ +--- +title: Slack Setup +sidebarTitle: Setup +description: Create a Slack App, configure OAuth scopes and event subscriptions, and deploy an Agno agent. +keywords: [slack, deploy, setup, oauth, scopes, events, ngrok, bot] +--- + +This guide walks you through creating a Slack App and connecting it to your Agno agent. + +## Setup + + + + +1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** +2. Choose **From scratch**, give it a name, and select your workspace +3. On the **Basic Information** page, copy the **Signing Secret** + + + +This is required for streaming task cards and suggested prompts. + +1. In the sidebar, click **Agents & AI Apps** +2. Toggle **Agent or Assistant** to **On** +3. Under **Suggested Prompts**, select **Dynamic** +4. Click **Save** + + +Enabling this automatically adds the `assistant:write` scope. + + + + +1. In the sidebar, click **OAuth & Permissions** +2. Under **Scopes > Bot Token Scopes**, add: + +| Scope | Purpose | +| --- | --- | +| `app_mentions:read` | Receive @mention events | +| `assistant:write` | Streaming (task cards, suggested prompts) | +| `chat:write` | Send messages and stream responses | +| `im:history` | Read DM history for thread context | +| `files:read` | Download files users send to the bot | +| `files:write` | Upload response files (images, docs) | + + +These are the minimum scopes for streaming. Add `channels:history`, `groups:history`, `users:read`, or `search:read` if your agent uses `SlackTools` for channel history, user lookup, or message search. + + +3. Click **Install to Workspace** and authorize the app +4. Copy the **Bot User OAuth Token** (`xoxb-...`) + + + +```bash +export SLACK_TOKEN="xoxb-your-bot-user-token" +export SLACK_SIGNING_SECRET="your-signing-secret" +``` + +Find these in your Slack App settings: +- **Bot User OAuth Token**: OAuth & Permissions +- **Signing Secret**: Basic Information > App Credentials + + + +1. In the sidebar, click **Event Subscriptions** +2. Toggle **Enable Events** to **On** +3. Set **Request URL** to your tunnel URL: + ``` + https:///slack/events + ``` + Your app must be running for Slack to verify the URL. + +4. Under **Subscribe to bot events**, add: + +| Event | Purpose | +| --- | --- | +| `app_mention` | Respond to @mentions in channels | +| `message.im` | Respond to direct messages | +| `assistant_thread_started` | Set suggested prompts on new threads | + + +Add `message.channels` and `message.groups` if you set `reply_to_mentions_only=False` and want the bot to respond to all channel messages. + + +5. Click **Save Changes** +6. Go to **Install App** and click **Reinstall to Workspace** + + + +1. In the sidebar, click **App Home** +2. Under **Show Tabs**, enable **Messages Tab** +3. Check **Allow users to send Slash commands and messages from the messages tab** + + + +Slack needs a public HTTPS URL to deliver events: + +```bash +ngrok http 7777 +``` + +Copy the `https://` forwarding URL and paste it into the Event Subscriptions Request URL (Step 5). The free ngrok tier gives you a random subdomain that changes on restart. + + + +```bash +python slack_bot.py +``` + +DM the bot or @mention it in a channel to test. + + + + + +ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). + + +## Scopes Reference + +Add scopes based on the features your bot uses. + +### Minimum (streaming bot that responds to mentions and DMs) + +| Scope | Required For | +| --- | --- | +| `app_mentions:read` | Receive @mention events in channels | +| `assistant:write` | Streaming task cards, suggested prompts, thread titles | +| `channels:read` | Resolve channel names (called on every inbound event) | +| `chat:write` | Send messages and stream responses | +| `im:history` | Read DM history for thread context | + +### File handling + +| Scope | Required For | +| --- | --- | +| `files:read` | Download files users attach to messages | +| `files:write` | Upload images, audio, video, and files generated by agent tools | + +### SlackTools methods + +| Scope | Required For | +| --- | --- | +| `channels:read` | `list_channels()`, `get_channel_info()` | +| `channels:history` | `get_channel_history()`, `get_thread()` in public channels | +| `groups:read` | `list_channels()` for private channels | +| `groups:history` | `get_channel_history()`, `get_thread()` in private channels | +| `search:read` | `search_messages()` (requires user token) | +| `search:read.public` | `search_workspace()` messages and channels | +| `search:read.files` | `search_workspace()` files | +| `search:read.users` | `search_workspace()` users | +| `users:read` | `list_users()`, `get_user_info()` | +| `users:read.email` | `get_user_info()` with email field | + +### Other features + +| Scope | Required For | +| --- | --- | +| `users:read` | `resolve_user_identity=True` on the Slack interface | +| `users:read.email` | `resolve_user_identity=True` with email lookup | +| `channels:history` | `reply_to_mentions_only=False` in public channels | +| `groups:history` | `reply_to_mentions_only=False` in private channels | + +### Event subscriptions + +| Event | Required For | +| --- | --- | +| `app_mention` | Respond to @mentions in channels | +| `message.im` | Respond to direct messages | +| `assistant_thread_started` | Set suggested prompts on new threads | +| `message.channels` | Respond to all public channel messages (`reply_to_mentions_only=False`) | +| `message.groups` | Respond to all private channel messages (`reply_to_mentions_only=False`) | + +## Next Steps + + + + Streaming, sessions, file handling, and behavior details. + + + All parameters, endpoints, and event handling. + + + Give agents outbound Slack actions: messaging, search, files. + + + Production deployment guides for AWS, GCP, and Docker. + + diff --git a/deploy/interfaces/telegram/overview.mdx b/deploy/interfaces/telegram/overview.mdx index 394d85286..4a482538d 100644 --- a/deploy/interfaces/telegram/overview.mdx +++ b/deploy/interfaces/telegram/overview.mdx @@ -40,7 +40,7 @@ python -m agno.os.serve telegram_agent:app --port 7777 ## Setup -Requires a bot token from [@BotFather](https://t.me/BotFather) and a webhook URL. See the [full setup guide](/agent-os/interfaces/telegram/introduction) for step-by-step instructions. +Requires a bot token from [@BotFather](https://t.me/BotFather) and a webhook URL. See the [setup guide](/deploy/interfaces/telegram/setup) for step-by-step instructions. **Environment variables:** ```bash diff --git a/deploy/interfaces/telegram/setup.mdx b/deploy/interfaces/telegram/setup.mdx new file mode 100644 index 000000000..8171e7f96 --- /dev/null +++ b/deploy/interfaces/telegram/setup.mdx @@ -0,0 +1,166 @@ +--- +title: Telegram Setup +sidebarTitle: Setup +description: Create a Telegram bot, configure webhooks, and deploy your Agno agent. +keywords: [telegram, deploy, setup, botfather, webhook, ngrok] +--- + +This guide walks you through setting up a Telegram bot from scratch. + +## Local Development + + + + +Ensure you have the following: +- A Telegram account +- ngrok (for development) +- Python 3.9+ + + + +1. Open Telegram and message [@BotFather](https://t.me/BotFather) +2. Send `/newbot` and follow the prompts to choose a display name and username (username must end in `bot`, e.g. `my_agno_bot`) +3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`) + + + +```bash +export TELEGRAM_TOKEN="your-bot-token-from-botfather" +export APP_ENV="development" # Bypasses webhook secret validation for local testing +``` + + + +Telegram needs a public HTTPS URL to deliver webhook events: +```bash +ngrok http 7777 +# Or, if you have a paid ngrok plan with a static domain: +# ngrok http --domain=your-custom-domain.ngrok-free.app 7777 +``` +Copy the `https://` forwarding URL provided by ngrok and set it as an environment variable: +```bash +export NGROK_URL=https://your-subdomain.ngrok-free.app +``` + + + +```bash +python telegram_bot.py +``` +The server starts on `http://localhost:7777`. + + + +Tell Telegram to send updates to your tunnel URL: +```bash +curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=${NGROK_URL}/telegram/webhook" +``` +You should see `{"ok":true,"result":true,"description":"Webhook was set"}`. + +Verify anytime with: +```bash +curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/getWebhookInfo" +``` + + + + +## Production Deployment + +In production, webhook secret validation is enforced. Telegram sends the secret in the `X-Telegram-Bot-Api-Secret-Token` header, and the interface rejects requests with an invalid or missing token with a `403`. + + + + +Generate a secret and set it as an environment variable: +```bash +export TELEGRAM_WEBHOOK_SECRET_TOKEN="your-random-secret-string" +``` + + + +Pass the `secret_token` parameter when registering your webhook: +```bash +curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=https://your-domain.com/telegram/webhook&secret_token=${TELEGRAM_WEBHOOK_SECRET_TOKEN}" +``` + + + +Do **not** set `APP_ENV=development` in production. Without it, webhook secret validation is active. + + + + + +ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). + + +## Group Chat Setup + +By default, Telegram bots in groups only receive commands (`/start`, etc.), @mentions, and replies to their own messages. To allow the bot to read all group messages: + + + + +1. Open a chat with [@BotFather](https://t.me/BotFather) +2. Send `/mybots` and select your bot +3. Go to **Bot Settings** > **Group Privacy** +4. Tap **Turn off** + +BotFather confirms: *"Privacy mode is disabled for YourBot."* + + + +Privacy mode changes only apply to groups the bot joins **after** the change. Remove and re-add the bot to any existing groups. Alternatively, making the bot a group admin bypasses privacy mode entirely. + + + +Control whether the bot responds to every message or only mentions: + +```python +Telegram( + agent=telegram_agent, + reply_to_mentions_only=True, # True (default): respond to @mentions and direct replies only + reply_to_bot_messages=True, # True (default): also respond when users reply to the bot's messages +) +``` + +Set `reply_to_mentions_only=False` to respond to all messages in the group. + + + + +## Environment Variables + +| Variable | Required | Description | +| -------- | -------- | ----------- | +| `TELEGRAM_TOKEN` | Yes | Bot token from @BotFather | +| `TELEGRAM_WEBHOOK_SECRET_TOKEN` | Production | Secret for webhook validation | +| `APP_ENV` | Dev only | Set to `development` to skip webhook secret validation | + +## Troubleshooting + +| Problem | Cause | Fix | +|---------|-------|-----| +| `403 Forbidden` on webhook | Missing or invalid webhook secret | Set `TELEGRAM_WEBHOOK_SECRET_TOKEN` and register the webhook with a matching `secret_token`, or set `APP_ENV=development` for local testing | +| Bot doesn't respond in groups | Privacy mode enabled | Disable privacy mode in BotFather and re-add the bot to the group | +| Bot doesn't respond at all | Webhook not registered or server not running | Verify with `getWebhookInfo` and check that your server is reachable | +| Streaming not working | `streaming` set to `False` | Set `streaming=True` on the `Telegram` interface (this is the default) | + +## Next Steps + + + + Streaming, sessions, media handling, and behavior details. + + + All parameters, endpoints, and events. + + + Basic, streaming, team, and workflow examples. + + + Production deployment guides for AWS, GCP, and Docker. + + diff --git a/deploy/interfaces/whatsapp/overview.mdx b/deploy/interfaces/whatsapp/overview.mdx index 3e6528cec..d7690622f 100644 --- a/deploy/interfaces/whatsapp/overview.mdx +++ b/deploy/interfaces/whatsapp/overview.mdx @@ -40,7 +40,7 @@ python -m agno.os.serve whatsapp_agent:app --port 7777 ## Setup -Requires a Meta Developer account, WhatsApp Business API access, and webhook configuration. See the [full setup guide](/agent-os/interfaces/whatsapp/introduction) for step-by-step instructions. +Requires a Meta Developer account, WhatsApp Business API access, and webhook configuration. See the [setup guide](/deploy/interfaces/whatsapp/setup) for step-by-step instructions. **Environment variables:** ```bash diff --git a/deploy/interfaces/whatsapp/setup.mdx b/deploy/interfaces/whatsapp/setup.mdx new file mode 100644 index 000000000..059243196 --- /dev/null +++ b/deploy/interfaces/whatsapp/setup.mdx @@ -0,0 +1,145 @@ +--- +title: WhatsApp Setup +sidebarTitle: Setup +description: Create a Meta App, configure the WhatsApp Business API, and deploy your Agno agent. +keywords: [whatsapp, deploy, setup, meta, webhook, ngrok] +--- + +This guide walks you through setting up WhatsApp Business API integration from scratch. + +## Setup + + + + +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) +- Python 3.9+ + + + +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. 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. + + + +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. + + + +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 +``` + +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): + ```bash + ngrok http 7777 + # Or, if you have a paid ngrok plan with a static domain: + # ngrok http --domain=your-custom-domain.ngrok-free.app 7777 + ``` +2. Copy the `https://` URL provided by ngrok. This is your base ngrok URL. +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`. + + + +For **development**, skip signature validation: +```bash +export WHATSAPP_SKIP_SIGNATURE_VALIDATION="true" +``` + +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. + +When `WHATSAPP_APP_SECRET` is set, every incoming webhook request is validated against the `X-Hub-Signature-256` header. Invalid requests receive a `403` response. + + + +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. + + + + + +ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). + + +## Environment Variables + +| Variable | Required | Description | +| -------- | -------- | ----------- | +| `WHATSAPP_ACCESS_TOKEN` | Yes | Bot access token from Meta App Dashboard or System User | +| `WHATSAPP_PHONE_NUMBER_ID` | Yes | Phone number ID from WhatsApp > API Setup | +| `WHATSAPP_VERIFY_TOKEN` | Yes | User-chosen string for webhook verification | +| `WHATSAPP_APP_SECRET` | Production | App Secret from App Settings > Basic. Enables signature validation. | +| `WHATSAPP_SKIP_SIGNATURE_VALIDATION` | Dev only | Set to `true` to bypass signature checks in development | +| `WHATSAPP_ENCRYPTION_KEY` | Optional | 64 hex char (32-byte) key for AES-256-GCM phone number encryption | + +## Next Steps + + + + Sessions, media handling, security, and behavior details. + + + All parameters, endpoints, and events. + + + Working examples on GitHub. + + + Production deployment guides for AWS, GCP, and Docker. + + diff --git a/docs.json b/docs.json index 59e293973..15e36b78a 100644 --- a/docs.json +++ b/docs.json @@ -4939,9 +4939,27 @@ { "group": "Interfaces", "pages": [ - "deploy/interfaces/slack/overview", - "deploy/interfaces/telegram/overview", - "deploy/interfaces/whatsapp/overview", + { + "group": "Slack", + "pages": [ + "deploy/interfaces/slack/overview", + "deploy/interfaces/slack/setup" + ] + }, + { + "group": "Telegram", + "pages": [ + "deploy/interfaces/telegram/overview", + "deploy/interfaces/telegram/setup" + ] + }, + { + "group": "WhatsApp", + "pages": [ + "deploy/interfaces/whatsapp/overview", + "deploy/interfaces/whatsapp/setup" + ] + }, "deploy/interfaces/discord/overview", "deploy/interfaces/ag-ui/overview", "deploy/interfaces/a2a/overview" From fb164c83bf092d4c0c9fc5243b066c1da66e6bde Mon Sep 17 00:00:00 2001 From: Mustafa Esoofally Date: Tue, 2 Jun 2026 17:19:04 -0400 Subject: [PATCH 2/9] fix: move setup steps into agent-os introduction pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Revised approach based on docs structure review: - Setup content now lives inline in agent-os/interfaces/{platform}/introduction.mdx - Deploy overview pages stay lightweight (quick start) and link to agent-os for full setup - Removed separate deploy/interfaces/{platform}/setup.mdx pages - Reverted docs.json to flat interface structure (no nested groups) This fixes the circular reference where deploy linked to agent-os and agent-os linked back to deploy, with neither having the actual setup steps. New flow: - deploy/.../overview.mdx → agent-os/.../introduction.mdx#setup (one-way) - Agent-OS introduction pages now have full inline for setup --- agent-os/interfaces/slack/introduction.mdx | 113 ++++++++++- agent-os/interfaces/telegram/introduction.mdx | 89 +++++++- agent-os/interfaces/whatsapp/introduction.mdx | 106 +++++++++- deploy/interfaces/slack/overview.mdx | 2 +- deploy/interfaces/slack/setup.mdx | 190 ------------------ deploy/interfaces/telegram/overview.mdx | 2 +- deploy/interfaces/telegram/setup.mdx | 166 --------------- deploy/interfaces/whatsapp/overview.mdx | 2 +- deploy/interfaces/whatsapp/setup.mdx | 145 ------------- docs.json | 24 +-- 10 files changed, 296 insertions(+), 543 deletions(-) delete mode 100644 deploy/interfaces/slack/setup.mdx delete mode 100644 deploy/interfaces/telegram/setup.mdx delete mode 100644 deploy/interfaces/whatsapp/setup.mdx diff --git a/agent-os/interfaces/slack/introduction.mdx b/agent-os/interfaces/slack/introduction.mdx index d5cd67ea0..04e8aca06 100644 --- a/agent-os/interfaces/slack/introduction.mdx +++ b/agent-os/interfaces/slack/introduction.mdx @@ -9,18 +9,117 @@ The Slack interface lets you deploy agents, teams, or workflows as interactive S ## Setup -Follow the [Slack setup guide](/deploy/interfaces/slack/setup) to create a Slack App and configure OAuth scopes, event subscriptions, and App Home. - Install the Slack dependencies: `uv pip install 'agno[slack]'` -Required configuration: + + + +1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** +2. Choose **From scratch**, give it a name, and select your workspace +3. On the **Basic Information** page, copy the **Signing Secret** + + + +This is required for streaming task cards and suggested prompts. + +1. In the sidebar, click **Agents & AI Apps** +2. Toggle **Agent or Assistant** to **On** +3. Under **Suggested Prompts**, select **Dynamic** +4. Click **Save** + + +Enabling this automatically adds the `assistant:write` scope. + + + + +1. In the sidebar, click **OAuth & Permissions** +2. Under **Scopes > Bot Token Scopes**, add: + +| Scope | Purpose | +| --- | --- | +| `app_mentions:read` | Receive @mention events | +| `assistant:write` | Streaming (task cards, suggested prompts) | +| `chat:write` | Send messages and stream responses | +| `im:history` | Read DM history for thread context | +| `files:read` | Download files users send to the bot | +| `files:write` | Upload response files (images, docs) | + + +These are the minimum scopes for streaming. Add `channels:history`, `groups:history`, `users:read`, or `search:read` if your agent uses `SlackTools` for channel history, user lookup, or message search. + + +3. Click **Install to Workspace** and authorize the app +4. Copy the **Bot User OAuth Token** (`xoxb-...`) + + + +```bash +export SLACK_TOKEN="xoxb-your-bot-user-token" +export SLACK_SIGNING_SECRET="your-signing-secret" +``` + +Find these in your Slack App settings: +- **Bot User OAuth Token**: OAuth & Permissions +- **Signing Secret**: Basic Information > App Credentials + + + +1. In the sidebar, click **Event Subscriptions** +2. Toggle **Enable Events** to **On** +3. Set **Request URL** to your tunnel URL: + ``` + https:///slack/events + ``` + Your app must be running for Slack to verify the URL. -- `SLACK_TOKEN` (Bot User OAuth Token) -- `SLACK_SIGNING_SECRET` (App Signing Secret) -- Webhook URL set to `{prefix}/events` (use [ngrok](https://ngrok.com) for local development) -- **Agents & AI Apps** enabled under App Home in your Slack App settings (required for streaming UI) +4. Under **Subscribe to bot events**, add: + +| Event | Purpose | +| --- | --- | +| `app_mention` | Respond to @mentions in channels | +| `message.im` | Respond to direct messages | +| `assistant_thread_started` | Set suggested prompts on new threads | + + +Add `message.channels` and `message.groups` if you set `reply_to_mentions_only=False` and want the bot to respond to all channel messages. + + +5. Click **Save Changes** +6. Go to **Install App** and click **Reinstall to Workspace** + + + +1. In the sidebar, click **App Home** +2. Under **Show Tabs**, enable **Messages Tab** +3. Check **Allow users to send Slash commands and messages from the messages tab** + + + +Slack needs a public HTTPS URL to deliver events: + +```bash +ngrok http 7777 +``` + +Copy the `https://` forwarding URL and paste it into the Event Subscriptions Request URL (Step 5). + + + +```bash +python slack_bot.py +``` + +DM the bot or @mention it in a channel to test. + + + + + +ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). + ## Example Usage diff --git a/agent-os/interfaces/telegram/introduction.mdx b/agent-os/interfaces/telegram/introduction.mdx index d1da0db1f..04be75962 100644 --- a/agent-os/interfaces/telegram/introduction.mdx +++ b/agent-os/interfaces/telegram/introduction.mdx @@ -9,13 +9,92 @@ The Telegram interface exposes an Agno Agent, Team, or Workflow on Telegram via ## Setup -Follow the [Telegram setup guide](/deploy/interfaces/telegram/setup) to set up your bot. +### Local Development + + + + +Ensure you have the following: +- A Telegram account +- ngrok (for development) +- Python 3.9+ + + + +1. Open Telegram and message [@BotFather](https://t.me/BotFather) +2. Send `/newbot` and follow the prompts to choose a display name and username (username must end in `bot`, e.g. `my_agno_bot`) +3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`) + + + +```bash +export TELEGRAM_TOKEN="your-bot-token-from-botfather" +export APP_ENV="development" # Bypasses webhook secret validation for local testing +``` + + + +Telegram needs a public HTTPS URL to deliver webhook events: +```bash +ngrok http 7777 +``` +Copy the `https://` forwarding URL provided by ngrok and set it as an environment variable: +```bash +export NGROK_URL=https://your-subdomain.ngrok-free.app +``` + + + +```bash +python telegram_bot.py +``` +The server starts on `http://localhost:7777`. + + + +Tell Telegram to send updates to your tunnel URL: +```bash +curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=${NGROK_URL}/telegram/webhook" +``` +You should see `{"ok":true,"result":true,"description":"Webhook was set"}`. + +Verify anytime with: +```bash +curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/getWebhookInfo" +``` + + + + +### Production Deployment + +In production, webhook secret validation is enforced. Telegram sends the secret in the `X-Telegram-Bot-Api-Secret-Token` header, and the interface rejects requests with an invalid or missing token with a `403`. + + + + +Generate a secret and set it as an environment variable: +```bash +export TELEGRAM_WEBHOOK_SECRET_TOKEN="your-random-secret-string" +``` + + + +Pass the `secret_token` parameter when registering your webhook: +```bash +curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=https://your-domain.com/telegram/webhook&secret_token=${TELEGRAM_WEBHOOK_SECRET_TOKEN}" +``` + + + +Do **not** set `APP_ENV=development` in production. Without it, webhook secret validation is active. + -Required configuration: + -- `TELEGRAM_TOKEN` (bot token from @BotFather) -- `TELEGRAM_WEBHOOK_SECRET_TOKEN` -- required in production, skipped when `APP_ENV=development` -- An ngrok tunnel (for local development) and webhook pointing to `/telegram/webhook` + +ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). + ## Example Usage diff --git a/agent-os/interfaces/whatsapp/introduction.mdx b/agent-os/interfaces/whatsapp/introduction.mdx index d21c44e32..4a87a15ce 100644 --- a/agent-os/interfaces/whatsapp/introduction.mdx +++ b/agent-os/interfaces/whatsapp/introduction.mdx @@ -9,14 +9,108 @@ The WhatsApp interface lets you deploy agents, teams, or workflows as WhatsApp b ## Setup -Follow the [WhatsApp setup guide](/deploy/interfaces/whatsapp/setup) to create a Meta App, configure the WhatsApp Business API, and set up webhooks. + + + +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) +- Python 3.9+ + + + +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. 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. + + + +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. + + + +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 +``` + +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): + ```bash + ngrok http 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`. + + + +For **development**, skip signature validation: +```bash +export WHATSAPP_SKIP_SIGNATURE_VALIDATION="true" +``` + +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. + + + +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. + -Required configuration: + -- `WHATSAPP_ACCESS_TOKEN` (from [Meta App Dashboard](https://developers.facebook.com/apps/) > WhatsApp > API Setup) -- `WHATSAPP_PHONE_NUMBER_ID` (from WhatsApp > API Setup) -- `WHATSAPP_VERIFY_TOKEN` (any string you choose for webhook verification) -- Webhook URL set to `{prefix}/webhook` (use [ngrok](https://ngrok.com) for local development) + +ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). + ## Example Usage diff --git a/deploy/interfaces/slack/overview.mdx b/deploy/interfaces/slack/overview.mdx index a789e61b7..5569a8cdc 100644 --- a/deploy/interfaces/slack/overview.mdx +++ b/deploy/interfaces/slack/overview.mdx @@ -40,7 +40,7 @@ python -m agno.os.serve slack_agent:app --port 7777 ## Setup -Requires a Slack App with OAuth scopes and event subscriptions. See the [setup guide](/deploy/interfaces/slack/setup) for step-by-step instructions. +Requires a Slack App with OAuth scopes and event subscriptions. See the [full guide](/agent-os/interfaces/slack/introduction#setup) for step-by-step setup instructions. **Environment variables:** ```bash diff --git a/deploy/interfaces/slack/setup.mdx b/deploy/interfaces/slack/setup.mdx deleted file mode 100644 index f60f8d100..000000000 --- a/deploy/interfaces/slack/setup.mdx +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Slack Setup -sidebarTitle: Setup -description: Create a Slack App, configure OAuth scopes and event subscriptions, and deploy an Agno agent. -keywords: [slack, deploy, setup, oauth, scopes, events, ngrok, bot] ---- - -This guide walks you through creating a Slack App and connecting it to your Agno agent. - -## Setup - - - - -1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** -2. Choose **From scratch**, give it a name, and select your workspace -3. On the **Basic Information** page, copy the **Signing Secret** - - - -This is required for streaming task cards and suggested prompts. - -1. In the sidebar, click **Agents & AI Apps** -2. Toggle **Agent or Assistant** to **On** -3. Under **Suggested Prompts**, select **Dynamic** -4. Click **Save** - - -Enabling this automatically adds the `assistant:write` scope. - - - - -1. In the sidebar, click **OAuth & Permissions** -2. Under **Scopes > Bot Token Scopes**, add: - -| Scope | Purpose | -| --- | --- | -| `app_mentions:read` | Receive @mention events | -| `assistant:write` | Streaming (task cards, suggested prompts) | -| `chat:write` | Send messages and stream responses | -| `im:history` | Read DM history for thread context | -| `files:read` | Download files users send to the bot | -| `files:write` | Upload response files (images, docs) | - - -These are the minimum scopes for streaming. Add `channels:history`, `groups:history`, `users:read`, or `search:read` if your agent uses `SlackTools` for channel history, user lookup, or message search. - - -3. Click **Install to Workspace** and authorize the app -4. Copy the **Bot User OAuth Token** (`xoxb-...`) - - - -```bash -export SLACK_TOKEN="xoxb-your-bot-user-token" -export SLACK_SIGNING_SECRET="your-signing-secret" -``` - -Find these in your Slack App settings: -- **Bot User OAuth Token**: OAuth & Permissions -- **Signing Secret**: Basic Information > App Credentials - - - -1. In the sidebar, click **Event Subscriptions** -2. Toggle **Enable Events** to **On** -3. Set **Request URL** to your tunnel URL: - ``` - https:///slack/events - ``` - Your app must be running for Slack to verify the URL. - -4. Under **Subscribe to bot events**, add: - -| Event | Purpose | -| --- | --- | -| `app_mention` | Respond to @mentions in channels | -| `message.im` | Respond to direct messages | -| `assistant_thread_started` | Set suggested prompts on new threads | - - -Add `message.channels` and `message.groups` if you set `reply_to_mentions_only=False` and want the bot to respond to all channel messages. - - -5. Click **Save Changes** -6. Go to **Install App** and click **Reinstall to Workspace** - - - -1. In the sidebar, click **App Home** -2. Under **Show Tabs**, enable **Messages Tab** -3. Check **Allow users to send Slash commands and messages from the messages tab** - - - -Slack needs a public HTTPS URL to deliver events: - -```bash -ngrok http 7777 -``` - -Copy the `https://` forwarding URL and paste it into the Event Subscriptions Request URL (Step 5). The free ngrok tier gives you a random subdomain that changes on restart. - - - -```bash -python slack_bot.py -``` - -DM the bot or @mention it in a channel to test. - - - - - -ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). - - -## Scopes Reference - -Add scopes based on the features your bot uses. - -### Minimum (streaming bot that responds to mentions and DMs) - -| Scope | Required For | -| --- | --- | -| `app_mentions:read` | Receive @mention events in channels | -| `assistant:write` | Streaming task cards, suggested prompts, thread titles | -| `channels:read` | Resolve channel names (called on every inbound event) | -| `chat:write` | Send messages and stream responses | -| `im:history` | Read DM history for thread context | - -### File handling - -| Scope | Required For | -| --- | --- | -| `files:read` | Download files users attach to messages | -| `files:write` | Upload images, audio, video, and files generated by agent tools | - -### SlackTools methods - -| Scope | Required For | -| --- | --- | -| `channels:read` | `list_channels()`, `get_channel_info()` | -| `channels:history` | `get_channel_history()`, `get_thread()` in public channels | -| `groups:read` | `list_channels()` for private channels | -| `groups:history` | `get_channel_history()`, `get_thread()` in private channels | -| `search:read` | `search_messages()` (requires user token) | -| `search:read.public` | `search_workspace()` messages and channels | -| `search:read.files` | `search_workspace()` files | -| `search:read.users` | `search_workspace()` users | -| `users:read` | `list_users()`, `get_user_info()` | -| `users:read.email` | `get_user_info()` with email field | - -### Other features - -| Scope | Required For | -| --- | --- | -| `users:read` | `resolve_user_identity=True` on the Slack interface | -| `users:read.email` | `resolve_user_identity=True` with email lookup | -| `channels:history` | `reply_to_mentions_only=False` in public channels | -| `groups:history` | `reply_to_mentions_only=False` in private channels | - -### Event subscriptions - -| Event | Required For | -| --- | --- | -| `app_mention` | Respond to @mentions in channels | -| `message.im` | Respond to direct messages | -| `assistant_thread_started` | Set suggested prompts on new threads | -| `message.channels` | Respond to all public channel messages (`reply_to_mentions_only=False`) | -| `message.groups` | Respond to all private channel messages (`reply_to_mentions_only=False`) | - -## Next Steps - - - - Streaming, sessions, file handling, and behavior details. - - - All parameters, endpoints, and event handling. - - - Give agents outbound Slack actions: messaging, search, files. - - - Production deployment guides for AWS, GCP, and Docker. - - diff --git a/deploy/interfaces/telegram/overview.mdx b/deploy/interfaces/telegram/overview.mdx index 4a482538d..a6a58a231 100644 --- a/deploy/interfaces/telegram/overview.mdx +++ b/deploy/interfaces/telegram/overview.mdx @@ -40,7 +40,7 @@ python -m agno.os.serve telegram_agent:app --port 7777 ## Setup -Requires a bot token from [@BotFather](https://t.me/BotFather) and a webhook URL. See the [setup guide](/deploy/interfaces/telegram/setup) for step-by-step instructions. +Requires a bot token from [@BotFather](https://t.me/BotFather) and a webhook URL. See the [full guide](/agent-os/interfaces/telegram/introduction#setup) for step-by-step setup instructions. **Environment variables:** ```bash diff --git a/deploy/interfaces/telegram/setup.mdx b/deploy/interfaces/telegram/setup.mdx deleted file mode 100644 index 8171e7f96..000000000 --- a/deploy/interfaces/telegram/setup.mdx +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Telegram Setup -sidebarTitle: Setup -description: Create a Telegram bot, configure webhooks, and deploy your Agno agent. -keywords: [telegram, deploy, setup, botfather, webhook, ngrok] ---- - -This guide walks you through setting up a Telegram bot from scratch. - -## Local Development - - - - -Ensure you have the following: -- A Telegram account -- ngrok (for development) -- Python 3.9+ - - - -1. Open Telegram and message [@BotFather](https://t.me/BotFather) -2. Send `/newbot` and follow the prompts to choose a display name and username (username must end in `bot`, e.g. `my_agno_bot`) -3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`) - - - -```bash -export TELEGRAM_TOKEN="your-bot-token-from-botfather" -export APP_ENV="development" # Bypasses webhook secret validation for local testing -``` - - - -Telegram needs a public HTTPS URL to deliver webhook events: -```bash -ngrok http 7777 -# Or, if you have a paid ngrok plan with a static domain: -# ngrok http --domain=your-custom-domain.ngrok-free.app 7777 -``` -Copy the `https://` forwarding URL provided by ngrok and set it as an environment variable: -```bash -export NGROK_URL=https://your-subdomain.ngrok-free.app -``` - - - -```bash -python telegram_bot.py -``` -The server starts on `http://localhost:7777`. - - - -Tell Telegram to send updates to your tunnel URL: -```bash -curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=${NGROK_URL}/telegram/webhook" -``` -You should see `{"ok":true,"result":true,"description":"Webhook was set"}`. - -Verify anytime with: -```bash -curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/getWebhookInfo" -``` - - - - -## Production Deployment - -In production, webhook secret validation is enforced. Telegram sends the secret in the `X-Telegram-Bot-Api-Secret-Token` header, and the interface rejects requests with an invalid or missing token with a `403`. - - - - -Generate a secret and set it as an environment variable: -```bash -export TELEGRAM_WEBHOOK_SECRET_TOKEN="your-random-secret-string" -``` - - - -Pass the `secret_token` parameter when registering your webhook: -```bash -curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=https://your-domain.com/telegram/webhook&secret_token=${TELEGRAM_WEBHOOK_SECRET_TOKEN}" -``` - - - -Do **not** set `APP_ENV=development` in production. Without it, webhook secret validation is active. - - - - - -ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). - - -## Group Chat Setup - -By default, Telegram bots in groups only receive commands (`/start`, etc.), @mentions, and replies to their own messages. To allow the bot to read all group messages: - - - - -1. Open a chat with [@BotFather](https://t.me/BotFather) -2. Send `/mybots` and select your bot -3. Go to **Bot Settings** > **Group Privacy** -4. Tap **Turn off** - -BotFather confirms: *"Privacy mode is disabled for YourBot."* - - - -Privacy mode changes only apply to groups the bot joins **after** the change. Remove and re-add the bot to any existing groups. Alternatively, making the bot a group admin bypasses privacy mode entirely. - - - -Control whether the bot responds to every message or only mentions: - -```python -Telegram( - agent=telegram_agent, - reply_to_mentions_only=True, # True (default): respond to @mentions and direct replies only - reply_to_bot_messages=True, # True (default): also respond when users reply to the bot's messages -) -``` - -Set `reply_to_mentions_only=False` to respond to all messages in the group. - - - - -## Environment Variables - -| Variable | Required | Description | -| -------- | -------- | ----------- | -| `TELEGRAM_TOKEN` | Yes | Bot token from @BotFather | -| `TELEGRAM_WEBHOOK_SECRET_TOKEN` | Production | Secret for webhook validation | -| `APP_ENV` | Dev only | Set to `development` to skip webhook secret validation | - -## Troubleshooting - -| Problem | Cause | Fix | -|---------|-------|-----| -| `403 Forbidden` on webhook | Missing or invalid webhook secret | Set `TELEGRAM_WEBHOOK_SECRET_TOKEN` and register the webhook with a matching `secret_token`, or set `APP_ENV=development` for local testing | -| Bot doesn't respond in groups | Privacy mode enabled | Disable privacy mode in BotFather and re-add the bot to the group | -| Bot doesn't respond at all | Webhook not registered or server not running | Verify with `getWebhookInfo` and check that your server is reachable | -| Streaming not working | `streaming` set to `False` | Set `streaming=True` on the `Telegram` interface (this is the default) | - -## Next Steps - - - - Streaming, sessions, media handling, and behavior details. - - - All parameters, endpoints, and events. - - - Basic, streaming, team, and workflow examples. - - - Production deployment guides for AWS, GCP, and Docker. - - diff --git a/deploy/interfaces/whatsapp/overview.mdx b/deploy/interfaces/whatsapp/overview.mdx index d7690622f..b6d6c3f3a 100644 --- a/deploy/interfaces/whatsapp/overview.mdx +++ b/deploy/interfaces/whatsapp/overview.mdx @@ -40,7 +40,7 @@ python -m agno.os.serve whatsapp_agent:app --port 7777 ## Setup -Requires a Meta Developer account, WhatsApp Business API access, and webhook configuration. See the [setup guide](/deploy/interfaces/whatsapp/setup) for step-by-step instructions. +Requires a Meta Developer account, WhatsApp Business API access, and webhook configuration. See the [full guide](/agent-os/interfaces/whatsapp/introduction#setup) for step-by-step setup instructions. **Environment variables:** ```bash diff --git a/deploy/interfaces/whatsapp/setup.mdx b/deploy/interfaces/whatsapp/setup.mdx deleted file mode 100644 index 059243196..000000000 --- a/deploy/interfaces/whatsapp/setup.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: WhatsApp Setup -sidebarTitle: Setup -description: Create a Meta App, configure the WhatsApp Business API, and deploy your Agno agent. -keywords: [whatsapp, deploy, setup, meta, webhook, ngrok] ---- - -This guide walks you through setting up WhatsApp Business API integration from scratch. - -## Setup - - - - -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) -- Python 3.9+ - - - -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. 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. - - - -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. - - - -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 -``` - -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): - ```bash - ngrok http 7777 - # Or, if you have a paid ngrok plan with a static domain: - # ngrok http --domain=your-custom-domain.ngrok-free.app 7777 - ``` -2. Copy the `https://` URL provided by ngrok. This is your base ngrok URL. -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`. - - - -For **development**, skip signature validation: -```bash -export WHATSAPP_SKIP_SIGNATURE_VALIDATION="true" -``` - -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. - -When `WHATSAPP_APP_SECRET` is set, every incoming webhook request is validated against the `X-Hub-Signature-256` header. Invalid requests receive a `403` response. - - - -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. - - - - - -ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). - - -## Environment Variables - -| Variable | Required | Description | -| -------- | -------- | ----------- | -| `WHATSAPP_ACCESS_TOKEN` | Yes | Bot access token from Meta App Dashboard or System User | -| `WHATSAPP_PHONE_NUMBER_ID` | Yes | Phone number ID from WhatsApp > API Setup | -| `WHATSAPP_VERIFY_TOKEN` | Yes | User-chosen string for webhook verification | -| `WHATSAPP_APP_SECRET` | Production | App Secret from App Settings > Basic. Enables signature validation. | -| `WHATSAPP_SKIP_SIGNATURE_VALIDATION` | Dev only | Set to `true` to bypass signature checks in development | -| `WHATSAPP_ENCRYPTION_KEY` | Optional | 64 hex char (32-byte) key for AES-256-GCM phone number encryption | - -## Next Steps - - - - Sessions, media handling, security, and behavior details. - - - All parameters, endpoints, and events. - - - Working examples on GitHub. - - - Production deployment guides for AWS, GCP, and Docker. - - diff --git a/docs.json b/docs.json index 15e36b78a..59e293973 100644 --- a/docs.json +++ b/docs.json @@ -4939,27 +4939,9 @@ { "group": "Interfaces", "pages": [ - { - "group": "Slack", - "pages": [ - "deploy/interfaces/slack/overview", - "deploy/interfaces/slack/setup" - ] - }, - { - "group": "Telegram", - "pages": [ - "deploy/interfaces/telegram/overview", - "deploy/interfaces/telegram/setup" - ] - }, - { - "group": "WhatsApp", - "pages": [ - "deploy/interfaces/whatsapp/overview", - "deploy/interfaces/whatsapp/setup" - ] - }, + "deploy/interfaces/slack/overview", + "deploy/interfaces/telegram/overview", + "deploy/interfaces/whatsapp/overview", "deploy/interfaces/discord/overview", "deploy/interfaces/ag-ui/overview", "deploy/interfaces/a2a/overview" From a7683f509f09cd4a85d5252bbe1b3c652ff159d5 Mon Sep 17 00:00:00 2001 From: Mustafa Esoofally Date: Tue, 2 Jun 2026 17:51:33 -0400 Subject: [PATCH 3/9] fix: create separate setup pages for interface docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create setup.mdx pages in agent-os for Slack, Telegram, WhatsApp - Remove inline setup content from introduction pages - Update docs.json sidebar: Introduction → Setup → (HITL) → Reference - Update deploy overview links to point to new setup pages --- agent-os/interfaces/slack/introduction.mdx | 114 ----------------- agent-os/interfaces/slack/setup.mdx | 118 ++++++++++++++++++ agent-os/interfaces/telegram/introduction.mdx | 89 ------------- agent-os/interfaces/telegram/setup.mdx | 97 ++++++++++++++ agent-os/interfaces/whatsapp/introduction.mdx | 105 ---------------- agent-os/interfaces/whatsapp/setup.mdx | 113 +++++++++++++++++ deploy/interfaces/slack/overview.mdx | 2 +- deploy/interfaces/telegram/overview.mdx | 2 +- deploy/interfaces/whatsapp/overview.mdx | 2 +- docs.json | 3 + 10 files changed, 334 insertions(+), 311 deletions(-) create mode 100644 agent-os/interfaces/slack/setup.mdx create mode 100644 agent-os/interfaces/telegram/setup.mdx create mode 100644 agent-os/interfaces/whatsapp/setup.mdx diff --git a/agent-os/interfaces/slack/introduction.mdx b/agent-os/interfaces/slack/introduction.mdx index 04e8aca06..b33b6d2ce 100644 --- a/agent-os/interfaces/slack/introduction.mdx +++ b/agent-os/interfaces/slack/introduction.mdx @@ -7,120 +7,6 @@ keywords: [slack, bot, interface, events, streaming, team, workflow, media, tool The Slack interface lets you deploy agents, teams, or workflows as interactive Slack bots. -## Setup - - -Install the Slack dependencies: `uv pip install 'agno[slack]'` - - - - - -1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** -2. Choose **From scratch**, give it a name, and select your workspace -3. On the **Basic Information** page, copy the **Signing Secret** - - - -This is required for streaming task cards and suggested prompts. - -1. In the sidebar, click **Agents & AI Apps** -2. Toggle **Agent or Assistant** to **On** -3. Under **Suggested Prompts**, select **Dynamic** -4. Click **Save** - - -Enabling this automatically adds the `assistant:write` scope. - - - - -1. In the sidebar, click **OAuth & Permissions** -2. Under **Scopes > Bot Token Scopes**, add: - -| Scope | Purpose | -| --- | --- | -| `app_mentions:read` | Receive @mention events | -| `assistant:write` | Streaming (task cards, suggested prompts) | -| `chat:write` | Send messages and stream responses | -| `im:history` | Read DM history for thread context | -| `files:read` | Download files users send to the bot | -| `files:write` | Upload response files (images, docs) | - - -These are the minimum scopes for streaming. Add `channels:history`, `groups:history`, `users:read`, or `search:read` if your agent uses `SlackTools` for channel history, user lookup, or message search. - - -3. Click **Install to Workspace** and authorize the app -4. Copy the **Bot User OAuth Token** (`xoxb-...`) - - - -```bash -export SLACK_TOKEN="xoxb-your-bot-user-token" -export SLACK_SIGNING_SECRET="your-signing-secret" -``` - -Find these in your Slack App settings: -- **Bot User OAuth Token**: OAuth & Permissions -- **Signing Secret**: Basic Information > App Credentials - - - -1. In the sidebar, click **Event Subscriptions** -2. Toggle **Enable Events** to **On** -3. Set **Request URL** to your tunnel URL: - ``` - https:///slack/events - ``` - Your app must be running for Slack to verify the URL. - -4. Under **Subscribe to bot events**, add: - -| Event | Purpose | -| --- | --- | -| `app_mention` | Respond to @mentions in channels | -| `message.im` | Respond to direct messages | -| `assistant_thread_started` | Set suggested prompts on new threads | - - -Add `message.channels` and `message.groups` if you set `reply_to_mentions_only=False` and want the bot to respond to all channel messages. - - -5. Click **Save Changes** -6. Go to **Install App** and click **Reinstall to Workspace** - - - -1. In the sidebar, click **App Home** -2. Under **Show Tabs**, enable **Messages Tab** -3. Check **Allow users to send Slash commands and messages from the messages tab** - - - -Slack needs a public HTTPS URL to deliver events: - -```bash -ngrok http 7777 -``` - -Copy the `https://` forwarding URL and paste it into the Event Subscriptions Request URL (Step 5). - - - -```bash -python slack_bot.py -``` - -DM the bot or @mention it in a channel to test. - - - - - -ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). - - ## Example Usage diff --git a/agent-os/interfaces/slack/setup.mdx b/agent-os/interfaces/slack/setup.mdx new file mode 100644 index 000000000..daad09341 --- /dev/null +++ b/agent-os/interfaces/slack/setup.mdx @@ -0,0 +1,118 @@ +--- +title: Setup +sidebarTitle: Setup +description: Create a Slack App, configure OAuth scopes, and set up event subscriptions for Slack bots. +keywords: [slack, setup, oauth, events, configuration, streaming] +--- + + +Install the Slack dependencies: `uv pip install 'agno[slack]'` + + + + + +1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** +2. Choose **From scratch**, give it a name, and select your workspace +3. On the **Basic Information** page, copy the **Signing Secret** + + + +This is required for streaming task cards and suggested prompts. + +1. In the sidebar, click **Agents & AI Apps** +2. Toggle **Agent or Assistant** to **On** +3. Under **Suggested Prompts**, select **Dynamic** +4. Click **Save** + + +Enabling this automatically adds the `assistant:write` scope. + + + + +1. In the sidebar, click **OAuth & Permissions** +2. Under **Scopes > Bot Token Scopes**, add: + +| Scope | Purpose | +| --- | --- | +| `app_mentions:read` | Receive @mention events | +| `assistant:write` | Streaming (task cards, suggested prompts) | +| `chat:write` | Send messages and stream responses | +| `im:history` | Read DM history for thread context | +| `files:read` | Download files users send to the bot | +| `files:write` | Upload response files (images, docs) | + + +These are the minimum scopes for streaming. Add `channels:history`, `groups:history`, `users:read`, or `search:read` if your agent uses `SlackTools` for channel history, user lookup, or message search. + + +3. Click **Install to Workspace** and authorize the app +4. Copy the **Bot User OAuth Token** (`xoxb-...`) + + + +```bash +export SLACK_TOKEN="xoxb-your-bot-user-token" +export SLACK_SIGNING_SECRET="your-signing-secret" +``` + +Find these in your Slack App settings: +- **Bot User OAuth Token**: OAuth & Permissions +- **Signing Secret**: Basic Information > App Credentials + + + +1. In the sidebar, click **Event Subscriptions** +2. Toggle **Enable Events** to **On** +3. Set **Request URL** to your tunnel URL: + ``` + https:///slack/events + ``` + Your app must be running for Slack to verify the URL. + +4. Under **Subscribe to bot events**, add: + +| Event | Purpose | +| --- | --- | +| `app_mention` | Respond to @mentions in channels | +| `message.im` | Respond to direct messages | +| `assistant_thread_started` | Set suggested prompts on new threads | + + +Add `message.channels` and `message.groups` if you set `reply_to_mentions_only=False` and want the bot to respond to all channel messages. + + +5. Click **Save Changes** +6. Go to **Install App** and click **Reinstall to Workspace** + + + +1. In the sidebar, click **App Home** +2. Under **Show Tabs**, enable **Messages Tab** +3. Check **Allow users to send Slash commands and messages from the messages tab** + + + +Slack needs a public HTTPS URL to deliver events: + +```bash +ngrok http 7777 +``` + +Copy the `https://` forwarding URL and paste it into the Event Subscriptions Request URL (Step 5). + + + +```bash +python slack_bot.py +``` + +DM the bot or @mention it in a channel to test. + + + + + +ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). + diff --git a/agent-os/interfaces/telegram/introduction.mdx b/agent-os/interfaces/telegram/introduction.mdx index 04be75962..14a459394 100644 --- a/agent-os/interfaces/telegram/introduction.mdx +++ b/agent-os/interfaces/telegram/introduction.mdx @@ -7,95 +7,6 @@ keywords: [telegram, bot, interface, webhook, streaming, group chat, media, tool The Telegram interface exposes an Agno Agent, Team, or Workflow on Telegram via FastAPI webhook endpoints. It handles inbound messages (text, photos, audio, video, documents, stickers) and streams responses back to the originating chat. -## Setup - -### Local Development - - - - -Ensure you have the following: -- A Telegram account -- ngrok (for development) -- Python 3.9+ - - - -1. Open Telegram and message [@BotFather](https://t.me/BotFather) -2. Send `/newbot` and follow the prompts to choose a display name and username (username must end in `bot`, e.g. `my_agno_bot`) -3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`) - - - -```bash -export TELEGRAM_TOKEN="your-bot-token-from-botfather" -export APP_ENV="development" # Bypasses webhook secret validation for local testing -``` - - - -Telegram needs a public HTTPS URL to deliver webhook events: -```bash -ngrok http 7777 -``` -Copy the `https://` forwarding URL provided by ngrok and set it as an environment variable: -```bash -export NGROK_URL=https://your-subdomain.ngrok-free.app -``` - - - -```bash -python telegram_bot.py -``` -The server starts on `http://localhost:7777`. - - - -Tell Telegram to send updates to your tunnel URL: -```bash -curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=${NGROK_URL}/telegram/webhook" -``` -You should see `{"ok":true,"result":true,"description":"Webhook was set"}`. - -Verify anytime with: -```bash -curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/getWebhookInfo" -``` - - - - -### Production Deployment - -In production, webhook secret validation is enforced. Telegram sends the secret in the `X-Telegram-Bot-Api-Secret-Token` header, and the interface rejects requests with an invalid or missing token with a `403`. - - - - -Generate a secret and set it as an environment variable: -```bash -export TELEGRAM_WEBHOOK_SECRET_TOKEN="your-random-secret-string" -``` - - - -Pass the `secret_token` parameter when registering your webhook: -```bash -curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=https://your-domain.com/telegram/webhook&secret_token=${TELEGRAM_WEBHOOK_SECRET_TOKEN}" -``` - - - -Do **not** set `APP_ENV=development` in production. Without it, webhook secret validation is active. - - - - - -ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). - - ## Example Usage Create an agent, expose it with the `Telegram` interface, and serve via `AgentOS`: diff --git a/agent-os/interfaces/telegram/setup.mdx b/agent-os/interfaces/telegram/setup.mdx new file mode 100644 index 000000000..b5f9172f8 --- /dev/null +++ b/agent-os/interfaces/telegram/setup.mdx @@ -0,0 +1,97 @@ +--- +title: Setup +sidebarTitle: Setup +description: Create a Telegram bot with BotFather and configure webhooks for local and production deployments. +keywords: [telegram, setup, botfather, webhook, configuration, ngrok] +--- + + +Install the Telegram dependencies: `uv pip install 'agno[telegram]'` + + +## Local Development + + + + +Ensure you have the following: +- A Telegram account +- ngrok (for development) +- Python 3.9+ + + + +1. Open Telegram and message [@BotFather](https://t.me/BotFather) +2. Send `/newbot` and follow the prompts to choose a display name and username (username must end in `bot`, e.g. `my_agno_bot`) +3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`) + + + +```bash +export TELEGRAM_TOKEN="your-bot-token-from-botfather" +export APP_ENV="development" # Bypasses webhook secret validation for local testing +``` + + + +Telegram needs a public HTTPS URL to deliver webhook events: +```bash +ngrok http 7777 +``` +Copy the `https://` forwarding URL provided by ngrok and set it as an environment variable: +```bash +export NGROK_URL=https://your-subdomain.ngrok-free.app +``` + + + +```bash +python telegram_bot.py +``` +The server starts on `http://localhost:7777`. + + + +Tell Telegram to send updates to your tunnel URL: +```bash +curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=${NGROK_URL}/telegram/webhook" +``` +You should see `{"ok":true,"result":true,"description":"Webhook was set"}`. + +Verify anytime with: +```bash +curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/getWebhookInfo" +``` + + + + +## Production Deployment + +In production, webhook secret validation is enforced. Telegram sends the secret in the `X-Telegram-Bot-Api-Secret-Token` header, and the interface rejects requests with an invalid or missing token with a `403`. + + + + +Generate a secret and set it as an environment variable: +```bash +export TELEGRAM_WEBHOOK_SECRET_TOKEN="your-random-secret-string" +``` + + + +Pass the `secret_token` parameter when registering your webhook: +```bash +curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=https://your-domain.com/telegram/webhook&secret_token=${TELEGRAM_WEBHOOK_SECRET_TOKEN}" +``` + + + +Do **not** set `APP_ENV=development` in production. Without it, webhook secret validation is active. + + + + + +ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). + diff --git a/agent-os/interfaces/whatsapp/introduction.mdx b/agent-os/interfaces/whatsapp/introduction.mdx index 4a87a15ce..b73bfb61d 100644 --- a/agent-os/interfaces/whatsapp/introduction.mdx +++ b/agent-os/interfaces/whatsapp/introduction.mdx @@ -7,111 +7,6 @@ keywords: [whatsapp, bot, interface, media, team, workflow, interactive, encrypt The WhatsApp interface lets you deploy agents, teams, or workflows as WhatsApp bots that handle text, images, video, audio, and documents. -## Setup - - - - -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) -- Python 3.9+ - - - -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. 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. - - - -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. - - - -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 -``` - -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): - ```bash - ngrok http 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`. - - - -For **development**, skip signature validation: -```bash -export WHATSAPP_SKIP_SIGNATURE_VALIDATION="true" -``` - -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. - - - -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. - - - - - -ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). - - ## Example Usage diff --git a/agent-os/interfaces/whatsapp/setup.mdx b/agent-os/interfaces/whatsapp/setup.mdx new file mode 100644 index 000000000..f3bbd257a --- /dev/null +++ b/agent-os/interfaces/whatsapp/setup.mdx @@ -0,0 +1,113 @@ +--- +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] +--- + + +Install the WhatsApp dependencies: `uv pip install 'agno[whatsapp]'` + + + + + +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) +- Python 3.9+ + + + +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. 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. + + + +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. + + + +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 +``` + +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): + ```bash + ngrok http 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`. + + + +For **development**, skip signature validation: +```bash +export WHATSAPP_SKIP_SIGNATURE_VALIDATION="true" +``` + +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. + + + +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. + + + + + +ngrok is for local development only. For production, see the [deployment templates](/deploy/templates). + diff --git a/deploy/interfaces/slack/overview.mdx b/deploy/interfaces/slack/overview.mdx index 5569a8cdc..36177f22f 100644 --- a/deploy/interfaces/slack/overview.mdx +++ b/deploy/interfaces/slack/overview.mdx @@ -40,7 +40,7 @@ python -m agno.os.serve slack_agent:app --port 7777 ## Setup -Requires a Slack App with OAuth scopes and event subscriptions. See the [full guide](/agent-os/interfaces/slack/introduction#setup) for step-by-step setup instructions. +Requires a Slack App with OAuth scopes and event subscriptions. See the [setup guide](/agent-os/interfaces/slack/setup) for step-by-step instructions. **Environment variables:** ```bash diff --git a/deploy/interfaces/telegram/overview.mdx b/deploy/interfaces/telegram/overview.mdx index a6a58a231..23c01303e 100644 --- a/deploy/interfaces/telegram/overview.mdx +++ b/deploy/interfaces/telegram/overview.mdx @@ -40,7 +40,7 @@ python -m agno.os.serve telegram_agent:app --port 7777 ## Setup -Requires a bot token from [@BotFather](https://t.me/BotFather) and a webhook URL. See the [full guide](/agent-os/interfaces/telegram/introduction#setup) for step-by-step setup instructions. +Requires a bot token from [@BotFather](https://t.me/BotFather) and a webhook URL. See the [setup guide](/agent-os/interfaces/telegram/setup) for step-by-step instructions. **Environment variables:** ```bash diff --git a/deploy/interfaces/whatsapp/overview.mdx b/deploy/interfaces/whatsapp/overview.mdx index b6d6c3f3a..1785dcfba 100644 --- a/deploy/interfaces/whatsapp/overview.mdx +++ b/deploy/interfaces/whatsapp/overview.mdx @@ -40,7 +40,7 @@ python -m agno.os.serve whatsapp_agent:app --port 7777 ## Setup -Requires a Meta Developer account, WhatsApp Business API access, and webhook configuration. See the [full guide](/agent-os/interfaces/whatsapp/introduction#setup) for step-by-step setup instructions. +Requires a Meta Developer account, WhatsApp Business API access, and webhook configuration. See the [setup guide](/agent-os/interfaces/whatsapp/setup) for step-by-step instructions. **Environment variables:** ```bash diff --git a/docs.json b/docs.json index 59e293973..6e09b5175 100644 --- a/docs.json +++ b/docs.json @@ -4652,6 +4652,7 @@ "group": "WhatsApp", "pages": [ "agent-os/interfaces/whatsapp/introduction", + "agent-os/interfaces/whatsapp/setup", "agent-os/interfaces/whatsapp/reference" ] }, @@ -4661,6 +4662,7 @@ "group": "Slack", "pages": [ "agent-os/interfaces/slack/introduction", + "agent-os/interfaces/slack/setup", "agent-os/interfaces/slack/hitl", "agent-os/interfaces/slack/reference" ] @@ -4669,6 +4671,7 @@ "group": "Telegram", "pages": [ "agent-os/interfaces/telegram/introduction", + "agent-os/interfaces/telegram/setup", "agent-os/interfaces/telegram/reference" ] } From d3c5f8613dc857a719c8a564fa36fc07d45890ba Mon Sep 17 00:00:00 2001 From: Mustafa Esoofally Date: Tue, 2 Jun 2026 17:53:10 -0400 Subject: [PATCH 4/9] fix: add brief setup overview to introduction pages --- agent-os/interfaces/slack/introduction.mdx | 12 ++++++++++++ agent-os/interfaces/telegram/introduction.mdx | 12 ++++++++++++ agent-os/interfaces/whatsapp/introduction.mdx | 14 ++++++++++++++ 3 files changed, 38 insertions(+) diff --git a/agent-os/interfaces/slack/introduction.mdx b/agent-os/interfaces/slack/introduction.mdx index b33b6d2ce..d527a0892 100644 --- a/agent-os/interfaces/slack/introduction.mdx +++ b/agent-os/interfaces/slack/introduction.mdx @@ -7,6 +7,18 @@ keywords: [slack, bot, interface, events, streaming, team, workflow, media, tool The Slack interface lets you deploy agents, teams, or workflows as interactive Slack bots. +## Setup + +Requires a Slack App with OAuth scopes and event subscriptions. + +**Environment variables:** +```bash +export SLACK_TOKEN="xoxb-..." +export SLACK_SIGNING_SECRET="..." +``` + +See the [full setup guide](/agent-os/interfaces/slack/setup) for step-by-step instructions. + ## Example Usage diff --git a/agent-os/interfaces/telegram/introduction.mdx b/agent-os/interfaces/telegram/introduction.mdx index 14a459394..00e7ffdb9 100644 --- a/agent-os/interfaces/telegram/introduction.mdx +++ b/agent-os/interfaces/telegram/introduction.mdx @@ -7,6 +7,18 @@ keywords: [telegram, bot, interface, webhook, streaming, group chat, media, tool The Telegram interface exposes an Agno Agent, Team, or Workflow on Telegram via FastAPI webhook endpoints. It handles inbound messages (text, photos, audio, video, documents, stickers) and streams responses back to the originating chat. +## Setup + +Requires a bot token from [@BotFather](https://t.me/BotFather) and a webhook URL. + +**Environment variables:** +```bash +export TELEGRAM_TOKEN="..." +export TELEGRAM_WEBHOOK_SECRET_TOKEN="..." # production only +``` + +See the [full setup guide](/agent-os/interfaces/telegram/setup) for step-by-step instructions. + ## Example Usage Create an agent, expose it with the `Telegram` interface, and serve via `AgentOS`: diff --git a/agent-os/interfaces/whatsapp/introduction.mdx b/agent-os/interfaces/whatsapp/introduction.mdx index b73bfb61d..6fb54fa1f 100644 --- a/agent-os/interfaces/whatsapp/introduction.mdx +++ b/agent-os/interfaces/whatsapp/introduction.mdx @@ -7,6 +7,20 @@ keywords: [whatsapp, bot, interface, media, team, workflow, interactive, encrypt The WhatsApp interface lets you deploy agents, teams, or workflows as WhatsApp bots that handle text, images, video, audio, and documents. +## Setup + +Requires a Meta Developer account, WhatsApp Business API access, and webhook configuration. + +**Environment variables:** +```bash +export WHATSAPP_ACCESS_TOKEN="..." +export WHATSAPP_PHONE_NUMBER_ID="..." +export WHATSAPP_VERIFY_TOKEN="..." +export WHATSAPP_APP_SECRET="..." # production +``` + +See the [full setup guide](/agent-os/interfaces/whatsapp/setup) for step-by-step instructions. + ## Example Usage From 022b2145f362e88253d6ff0f9baf62455dd50f73 Mon Sep 17 00:00:00 2001 From: Mustafa Esoofally Date: Tue, 2 Jun 2026 17:55:08 -0400 Subject: [PATCH 5/9] fix: restore original introduction content, update links to setup pages --- agent-os/interfaces/slack/introduction.mdx | 17 ++++++++++------- agent-os/interfaces/telegram/introduction.mdx | 12 +++++------- agent-os/interfaces/whatsapp/introduction.mdx | 17 +++++++---------- 3 files changed, 22 insertions(+), 24 deletions(-) diff --git a/agent-os/interfaces/slack/introduction.mdx b/agent-os/interfaces/slack/introduction.mdx index d527a0892..6d403534c 100644 --- a/agent-os/interfaces/slack/introduction.mdx +++ b/agent-os/interfaces/slack/introduction.mdx @@ -9,15 +9,18 @@ The Slack interface lets you deploy agents, teams, or workflows as interactive S ## Setup -Requires a Slack App with OAuth scopes and event subscriptions. +Follow the [Slack setup guide](/agent-os/interfaces/slack/setup) to create a Slack App and configure OAuth scopes, event subscriptions, and App Home. -**Environment variables:** -```bash -export SLACK_TOKEN="xoxb-..." -export SLACK_SIGNING_SECRET="..." -``` + +Install the Slack dependencies: `uv pip install 'agno[slack]'` + + +Required configuration: -See the [full setup guide](/agent-os/interfaces/slack/setup) for step-by-step instructions. +- `SLACK_TOKEN` (Bot User OAuth Token) +- `SLACK_SIGNING_SECRET` (App Signing Secret) +- Webhook URL set to `{prefix}/events` (use [ngrok](https://ngrok.com) for local development) +- **Agents & AI Apps** enabled under App Home in your Slack App settings (required for streaming UI) ## Example Usage diff --git a/agent-os/interfaces/telegram/introduction.mdx b/agent-os/interfaces/telegram/introduction.mdx index 00e7ffdb9..9248b1404 100644 --- a/agent-os/interfaces/telegram/introduction.mdx +++ b/agent-os/interfaces/telegram/introduction.mdx @@ -9,15 +9,13 @@ The Telegram interface exposes an Agno Agent, Team, or Workflow on Telegram via ## Setup -Requires a bot token from [@BotFather](https://t.me/BotFather) and a webhook URL. +Follow the [Telegram setup guide](/agent-os/interfaces/telegram/setup) to set up your bot. -**Environment variables:** -```bash -export TELEGRAM_TOKEN="..." -export TELEGRAM_WEBHOOK_SECRET_TOKEN="..." # production only -``` +Required configuration: -See the [full setup guide](/agent-os/interfaces/telegram/setup) for step-by-step instructions. +- `TELEGRAM_TOKEN` (bot token from @BotFather) +- `TELEGRAM_WEBHOOK_SECRET_TOKEN` -- required in production, skipped when `APP_ENV=development` +- An ngrok tunnel (for local development) and webhook pointing to `/telegram/webhook` ## Example Usage diff --git a/agent-os/interfaces/whatsapp/introduction.mdx b/agent-os/interfaces/whatsapp/introduction.mdx index 6fb54fa1f..e4e74f55b 100644 --- a/agent-os/interfaces/whatsapp/introduction.mdx +++ b/agent-os/interfaces/whatsapp/introduction.mdx @@ -9,17 +9,14 @@ The WhatsApp interface lets you deploy agents, teams, or workflows as WhatsApp b ## Setup -Requires a Meta Developer account, WhatsApp Business API access, and webhook configuration. - -**Environment variables:** -```bash -export WHATSAPP_ACCESS_TOKEN="..." -export WHATSAPP_PHONE_NUMBER_ID="..." -export WHATSAPP_VERIFY_TOKEN="..." -export WHATSAPP_APP_SECRET="..." # production -``` +Follow the [WhatsApp setup guide](/agent-os/interfaces/whatsapp/setup) to create a Meta App, configure the WhatsApp Business API, and set up webhooks. + +Required configuration: -See the [full setup guide](/agent-os/interfaces/whatsapp/setup) for step-by-step instructions. +- `WHATSAPP_ACCESS_TOKEN` (from [Meta App Dashboard](https://developers.facebook.com/apps/) > WhatsApp > API Setup) +- `WHATSAPP_PHONE_NUMBER_ID` (from WhatsApp > API Setup) +- `WHATSAPP_VERIFY_TOKEN` (any string you choose for webhook verification) +- Webhook URL set to `{prefix}/webhook` (use [ngrok](https://ngrok.com) for local development) ## Example Usage From c45a5f1d90032f54fcf48b05863dd940408d5e1e Mon Sep 17 00:00:00 2001 From: Mustafa Esoofally Date: Tue, 2 Jun 2026 17:58:35 -0400 Subject: [PATCH 6/9] fix: reorder interfaces sidebar - Slack first --- docs.json | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs.json b/docs.json index 6e09b5175..5d672389d 100644 --- a/docs.json +++ b/docs.json @@ -4648,16 +4648,6 @@ "group": "Interfaces", "pages": [ "agent-os/interfaces/overview", - { - "group": "WhatsApp", - "pages": [ - "agent-os/interfaces/whatsapp/introduction", - "agent-os/interfaces/whatsapp/setup", - "agent-os/interfaces/whatsapp/reference" - ] - }, - "agent-os/interfaces/a2a/introduction", - "agent-os/interfaces/ag-ui/introduction", { "group": "Slack", "pages": [ @@ -4674,7 +4664,17 @@ "agent-os/interfaces/telegram/setup", "agent-os/interfaces/telegram/reference" ] - } + }, + { + "group": "WhatsApp", + "pages": [ + "agent-os/interfaces/whatsapp/introduction", + "agent-os/interfaces/whatsapp/setup", + "agent-os/interfaces/whatsapp/reference" + ] + }, + "agent-os/interfaces/a2a/introduction", + "agent-os/interfaces/ag-ui/introduction" ] }, { From a06706a3ea676ea628e3653671e5d3006e973a0b Mon Sep 17 00:00:00 2001 From: Mustafa Esoofally Date: Tue, 2 Jun 2026 18:00:15 -0400 Subject: [PATCH 7/9] fix: rename interface introduction.mdx to overview.mdx --- .../interfaces/slack/{introduction.mdx => overview.mdx} | 2 +- .../interfaces/telegram/{introduction.mdx => overview.mdx} | 2 +- .../interfaces/whatsapp/{introduction.mdx => overview.mdx} | 2 +- docs.json | 6 +++--- 4 files changed, 6 insertions(+), 6 deletions(-) rename agent-os/interfaces/slack/{introduction.mdx => overview.mdx} (99%) rename agent-os/interfaces/telegram/{introduction.mdx => overview.mdx} (99%) rename agent-os/interfaces/whatsapp/{introduction.mdx => overview.mdx} (99%) diff --git a/agent-os/interfaces/slack/introduction.mdx b/agent-os/interfaces/slack/overview.mdx similarity index 99% rename from agent-os/interfaces/slack/introduction.mdx rename to agent-os/interfaces/slack/overview.mdx index 6d403534c..2a14310db 100644 --- a/agent-os/interfaces/slack/introduction.mdx +++ b/agent-os/interfaces/slack/overview.mdx @@ -1,6 +1,6 @@ --- title: Slack -sidebarTitle: Slack +sidebarTitle: Overview description: Deploy agents, teams, or workflows as interactive Slack bots. keywords: [slack, bot, interface, events, streaming, team, workflow, media, tools, task cards] --- diff --git a/agent-os/interfaces/telegram/introduction.mdx b/agent-os/interfaces/telegram/overview.mdx similarity index 99% rename from agent-os/interfaces/telegram/introduction.mdx rename to agent-os/interfaces/telegram/overview.mdx index 9248b1404..9fd23939a 100644 --- a/agent-os/interfaces/telegram/introduction.mdx +++ b/agent-os/interfaces/telegram/overview.mdx @@ -1,6 +1,6 @@ --- title: Telegram -sidebarTitle: "Telegram" +sidebarTitle: Overview description: "Expose agents, teams, or workflows as Telegram bots with webhook endpoints." keywords: [telegram, bot, interface, webhook, streaming, group chat, media, tools] --- diff --git a/agent-os/interfaces/whatsapp/introduction.mdx b/agent-os/interfaces/whatsapp/overview.mdx similarity index 99% rename from agent-os/interfaces/whatsapp/introduction.mdx rename to agent-os/interfaces/whatsapp/overview.mdx index e4e74f55b..01db2a8fa 100644 --- a/agent-os/interfaces/whatsapp/introduction.mdx +++ b/agent-os/interfaces/whatsapp/overview.mdx @@ -1,6 +1,6 @@ --- title: WhatsApp -sidebarTitle: WhatsApp +sidebarTitle: Overview description: Deploy agents, teams, or workflows as WhatsApp bots via the WhatsApp Interface using Agno. keywords: [whatsapp, bot, interface, media, team, workflow, interactive, encryption, webhook] --- diff --git a/docs.json b/docs.json index 5d672389d..d5e422203 100644 --- a/docs.json +++ b/docs.json @@ -4651,7 +4651,7 @@ { "group": "Slack", "pages": [ - "agent-os/interfaces/slack/introduction", + "agent-os/interfaces/slack/overview", "agent-os/interfaces/slack/setup", "agent-os/interfaces/slack/hitl", "agent-os/interfaces/slack/reference" @@ -4660,7 +4660,7 @@ { "group": "Telegram", "pages": [ - "agent-os/interfaces/telegram/introduction", + "agent-os/interfaces/telegram/overview", "agent-os/interfaces/telegram/setup", "agent-os/interfaces/telegram/reference" ] @@ -4668,7 +4668,7 @@ { "group": "WhatsApp", "pages": [ - "agent-os/interfaces/whatsapp/introduction", + "agent-os/interfaces/whatsapp/overview", "agent-os/interfaces/whatsapp/setup", "agent-os/interfaces/whatsapp/reference" ] From 9b621bb740755439d3e7b55ff97f9cc254ea4d5b Mon Sep 17 00:00:00 2001 From: Mustafa Esoofally Date: Tue, 2 Jun 2026 18:03:59 -0400 Subject: [PATCH 8/9] fix: reorder Slack sidebar - overview, hitl, setup, reference --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index d5e422203..9a9a0d6ce 100644 --- a/docs.json +++ b/docs.json @@ -4652,8 +4652,8 @@ "group": "Slack", "pages": [ "agent-os/interfaces/slack/overview", - "agent-os/interfaces/slack/setup", "agent-os/interfaces/slack/hitl", + "agent-os/interfaces/slack/setup", "agent-os/interfaces/slack/reference" ] }, From 0523a94b07475c24bf178603f5bf573c006ecd18 Mon Sep 17 00:00:00 2001 From: Mustafa Esoofally Date: Tue, 2 Jun 2026 18:07:48 -0400 Subject: [PATCH 9/9] fix: keep introduction.mdx filenames, use sidebarTitle: Overview --- .../interfaces/slack/{overview.mdx => introduction.mdx} | 0 .../interfaces/telegram/{overview.mdx => introduction.mdx} | 0 .../interfaces/whatsapp/{overview.mdx => introduction.mdx} | 0 docs.json | 6 +++--- 4 files changed, 3 insertions(+), 3 deletions(-) rename agent-os/interfaces/slack/{overview.mdx => introduction.mdx} (100%) rename agent-os/interfaces/telegram/{overview.mdx => introduction.mdx} (100%) rename agent-os/interfaces/whatsapp/{overview.mdx => introduction.mdx} (100%) diff --git a/agent-os/interfaces/slack/overview.mdx b/agent-os/interfaces/slack/introduction.mdx similarity index 100% rename from agent-os/interfaces/slack/overview.mdx rename to agent-os/interfaces/slack/introduction.mdx diff --git a/agent-os/interfaces/telegram/overview.mdx b/agent-os/interfaces/telegram/introduction.mdx similarity index 100% rename from agent-os/interfaces/telegram/overview.mdx rename to agent-os/interfaces/telegram/introduction.mdx diff --git a/agent-os/interfaces/whatsapp/overview.mdx b/agent-os/interfaces/whatsapp/introduction.mdx similarity index 100% rename from agent-os/interfaces/whatsapp/overview.mdx rename to agent-os/interfaces/whatsapp/introduction.mdx diff --git a/docs.json b/docs.json index 9a9a0d6ce..d018848b4 100644 --- a/docs.json +++ b/docs.json @@ -4651,7 +4651,7 @@ { "group": "Slack", "pages": [ - "agent-os/interfaces/slack/overview", + "agent-os/interfaces/slack/introduction", "agent-os/interfaces/slack/hitl", "agent-os/interfaces/slack/setup", "agent-os/interfaces/slack/reference" @@ -4660,7 +4660,7 @@ { "group": "Telegram", "pages": [ - "agent-os/interfaces/telegram/overview", + "agent-os/interfaces/telegram/introduction", "agent-os/interfaces/telegram/setup", "agent-os/interfaces/telegram/reference" ] @@ -4668,7 +4668,7 @@ { "group": "WhatsApp", "pages": [ - "agent-os/interfaces/whatsapp/overview", + "agent-os/interfaces/whatsapp/introduction", "agent-os/interfaces/whatsapp/setup", "agent-os/interfaces/whatsapp/reference" ]