agno-agi · Mustafa-Esoofally · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026
diff --git a/agent-os/interfaces/slack/introduction.mdx b/agent-os/interfaces/slack/introduction.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]
 ---
@@ -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](/agent-os/interfaces/slack/setup) to create a Slack App and configure OAuth scopes, event subscriptions, and App Home.
 
 <Note>
 Install the Slack dependencies: `uv pip install 'agno[slack]'`

diff --git a/agent-os/interfaces/slack/setup.mdx 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]
+---
+
+<Note>
+Install the Slack dependencies: `uv pip install 'agno[slack]'`
+</Note>
+
+<Steps>
+
+<Step title="Create a Slack App">
+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**
+</Step>
+
+<Step title="Enable Agents & AI Apps">
+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**
+
+<Note>
+Enabling this automatically adds the `assistant:write` scope.
+</Note>
+</Step>
+
+<Step title="Add OAuth Scopes">
+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) |
+
+<Tip>
+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.
+</Tip>
+
+3. Click **Install to Workspace** and authorize the app
+4. Copy the **Bot User OAuth Token** (`xoxb-...`)
+</Step>
+
+<Step title="Set Environment Variables">
+```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
+</Step>
+
+<Step title="Subscribe to Events">
+1. In the sidebar, click **Event Subscriptions**
+2. Toggle **Enable Events** to **On**
+3. Set **Request URL** to your tunnel URL:
+   ```
+   https://<your-tunnel>/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 |
+
+<Tip>
+Add `message.channels` and `message.groups` if you set `reply_to_mentions_only=False` and want the bot to respond to all channel messages.
+</Tip>
+
+5. Click **Save Changes**
+6. Go to **Install App** and click **Reinstall to Workspace**
+</Step>
+
+<Step title="Enable App Home">
+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**
+</Step>
+
+<Step title="Start a Tunnel">
+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).
+</Step>
+
+<Step title="Run the App">
+```bash
+python slack_bot.py
+```
+
+DM the bot or @mention it in a channel to test.
+</Step>
+
+</Steps>
+
+<Warning>
+ngrok is for local development only. For production, see the [deployment templates](/deploy/templates).
+</Warning>
diff --git a/agent-os/interfaces/telegram/introduction.mdx b/agent-os/interfaces/telegram/introduction.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]
 ---
@@ -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](/agent-os/interfaces/telegram/setup) to set up your bot.
 
 Required configuration:
 

diff --git a/agent-os/interfaces/telegram/setup.mdx 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]
+---
+
+<Note>
+Install the Telegram dependencies: `uv pip install 'agno[telegram]'`
+</Note>
+
+## Local Development
+
+<Steps>
+
+<Step title="Prerequisites">
+Ensure you have the following:
+- A Telegram account
+- ngrok (for development)
+- Python 3.9+
+</Step>
+
+<Step title="Create a Telegram Bot">
+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`)
+</Step>
+
+<Step title="Set Environment Variables">
+```bash
+export TELEGRAM_TOKEN="your-bot-token-from-botfather"
+export APP_ENV="development"  # Bypasses webhook secret validation for local testing
+```
+</Step>
+
+<Step title="Start a Tunnel with ngrok">
+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
+```
+</Step>
+
+<Step title="Run the App">
+```bash
+python telegram_bot.py
+```
+The server starts on `http://localhost:7777`.
+</Step>
+
+<Step title="Register the Webhook">
+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"
+```
+</Step>
+
+</Steps>
+
+## 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`.
+
+<Steps>
+
+<Step title="Set the Webhook Secret">
+Generate a secret and set it as an environment variable:
+```bash
+export TELEGRAM_WEBHOOK_SECRET_TOKEN="your-random-secret-string"
+```
+</Step>
+
+<Step title="Register the Webhook with the Secret">
+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}"
+```
+</Step>
+
+<Step title="Remove APP_ENV=development">
+Do **not** set `APP_ENV=development` in production. Without it, webhook secret validation is active.
+</Step>
+
+</Steps>
+
+<Warning>
+ngrok is for local development only. For production, see the [deployment templates](/deploy/templates).
+</Warning>
diff --git a/agent-os/interfaces/whatsapp/introduction.mdx b/agent-os/interfaces/whatsapp/introduction.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]
 ---
@@ -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](/agent-os/interfaces/whatsapp/setup) to create a Meta App, configure the WhatsApp Business API, and set up webhooks.
 
 Required configuration:
 

diff --git a/agent-os/interfaces/whatsapp/setup.mdx 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]
+---
+
+<Note>
+Install the WhatsApp dependencies: `uv pip install 'agno[whatsapp]'`
+</Note>
+
+<Steps>
+
+<Step title="Prerequisites">
+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+
+</Step>
+
+<Step title="Create a Meta App">
+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.
+</Step>
+
+<Step title="Set Up a Meta Business Account">
+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.
+</Step>
+
+<Step title="Configure WhatsApp Business API">
+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.
+</Step>
+
+<Step title="Set Up Environment Variables">
+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.
+</Step>
+
+<Step title="Set Up Webhook with ngrok">
+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://<your-ngrok-url>/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`.
+</Step>
+
+<Step title="Configure Signature Validation">
+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.
+</Step>
+
+<Step title="Test Your Bot">
+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.
+</Step>
+
+</Steps>
+
+<Warning>
+ngrok is for local development only. For production, see the [deployment templates](/deploy/templates).
+</Warning>
diff --git 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](/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
@@ -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](/agent-os/interfaces/telegram/setup) for step-by-step instructions.
 
 **Environment variables:**
 ```bash