diff --git a/agent-os/interfaces/slack/introduction.mdx b/agent-os/interfaces/slack/introduction.mdx index e13133b9a..2a14310db 100644 --- 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. 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 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 38bdfffe3..9fd23939a 100644 --- 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 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 c0c83ab20..01db2a8fa 100644 --- 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 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 5ee171be2..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 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 index 394d85286..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 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 diff --git a/deploy/interfaces/whatsapp/overview.mdx b/deploy/interfaces/whatsapp/overview.mdx index 3e6528cec..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 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](/agent-os/interfaces/whatsapp/setup) for step-by-step instructions. **Environment variables:** ```bash diff --git a/docs.json b/docs.json index 59e293973..d018848b4 100644 --- a/docs.json +++ b/docs.json @@ -4648,20 +4648,12 @@ "group": "Interfaces", "pages": [ "agent-os/interfaces/overview", - { - "group": "WhatsApp", - "pages": [ - "agent-os/interfaces/whatsapp/introduction", - "agent-os/interfaces/whatsapp/reference" - ] - }, - "agent-os/interfaces/a2a/introduction", - "agent-os/interfaces/ag-ui/introduction", { "group": "Slack", "pages": [ "agent-os/interfaces/slack/introduction", "agent-os/interfaces/slack/hitl", + "agent-os/interfaces/slack/setup", "agent-os/interfaces/slack/reference" ] }, @@ -4669,9 +4661,20 @@ "group": "Telegram", "pages": [ "agent-os/interfaces/telegram/introduction", + "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" ] }, {