Bot Integrations Guide

Last Updated: 2026-01-23

Aragora is the control plane for multi-agent vetted decisionmaking across organizational knowledge and channels. It is omnivorous by design—communicating bidirectionally across multiple channels. Query from wherever you work; get defensible decisions delivered back to you.

Output Channels: Web, Slack, Discord, Microsoft Teams, Zoom, WhatsApp Business, Telegram, API.

This guide covers setting up Aragora bots for various chat platforms to enable bidirectional communication - running debates and receiving results directly from your team's chat.

Table of Contents

• Overview
• Common Commands
• Discord
• Microsoft Teams
• Zoom
• Slack
• Telegram
• WhatsApp Business
• Architecture
• Troubleshooting

---

Overview

Aragora bots allow your team to:

• Start multi-agent debates from chat
• Run stress-test validations on decisions
• Check system status
• Vote on debate outcomes
• Receive debate results in threads

All platforms share a common command framework, so the experience is consistent across Discord, Teams, Zoom, and Slack.

---

Common Commands

Command	Description	Platforms
/aragora debate "topic"	Start a multi-agent debate	All
/aragora gauntlet	Run adversarial stress-test	Slack, Discord, Teams (with file attachment)
/aragora status	Check Aragora system status	All
/aragora help	List available commands	All

Example:

/aragora debate "Should we migrate to microservices?"

---

Discord

Prerequisites

• A Discord server where you have admin permissions
• Access to Discord Developer Portal

Step 1: Create Discord Application

1. Go to Discord Developer Portal
2. Click "New Application" and name it (e.g., "Aragora")
3. Note the Application ID from "General Information"
4. Copy the Public Key from "General Information"

Step 2: Create Bot User

1. Go to "Bot" in the left sidebar
2. Click "Add Bot"
3. Copy the Bot Token (keep this secret!)
4. Enable these Privileged Gateway Intents:
   • Message Content Intent

Step 3: Configure Slash Commands

1. Go to "OAuth2" > "URL Generator"
2. Select scopes: bot, applications.commands
3. Select bot permissions:
   • Send Messages
   • Send Messages in Threads
   • Embed Links
   • Attach Files
   • Read Message History
   • Use Slash Commands
4. Use the generated URL to invite the bot to your server

Step 4: Set Up Interactions Endpoint

1. Go to "General Information"
2. Set Interactions Endpoint URL to:

   https://your-api.aragora.ai/api/bots/discord/interactions

3. Discord will verify the endpoint (requires your server to be running)

Step 5: Configure Environment

DISCORD_BOT_TOKEN=your-bot-token
DISCORD_APPLICATION_ID=your-application-id
DISCORD_PUBLIC_KEY=your-public-key

Usage

Slash Commands:

/debate topic:Should AI be regulated?
/gauntlet statement:Our Q4 projections are accurate
/status

Bot Mention:

@Aragora debate Should we use GraphQL or REST?

Voting: After a debate, click the Agree or Disagree button to vote.

---

Microsoft Teams

Prerequisites

• Azure subscription
• Admin access to Teams Admin Center
• Access to Azure Portal

Step 1: Create Azure Bot

1. Go to Azure Portal
2. Search for "Azure Bot" and click Create
3. Fill in:
   • Bot handle: aragora-bot
   • Subscription: Your subscription
   • Resource group: Create new or use existing
   • Pricing tier: F0 (free) or S1
   • App ID: Create new Microsoft App ID
4. Click "Review + create"

Step 2: Configure Bot

1. Go to your bot resource
2. Under "Settings" > "Configuration":
   • Set Messaging endpoint to:

     https://your-api.aragora.ai/api/bots/teams/messages

3. Under "Channels", add "Microsoft Teams"
4. Note the App ID and create a App Password (Client Secret)

Step 3: Create Teams App Manifest

Create manifest.json:

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.14/MicrosoftTeams.schema.json",
  "manifestVersion": "1.14",
  "version": "1.0.0",
  "id": "your-app-id",
  "packageName": "ai.aragora.teams",
  "developer": {
    "name": "Aragora",
    "websiteUrl": "https://aragora.ai",
    "privacyUrl": "https://aragora.ai/privacy",
    "termsOfUseUrl": "https://aragora.ai/terms"
  },
  "name": {
    "short": "Aragora",
    "full": "Aragora Multi-Agent Debate"
  },
  "description": {
    "short": "Multi-agent debate and validation",
    "full": "Run multi-agent debates and stress-test validations directly in Teams"
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "bots": [
    {
      "botId": "your-app-id",
      "scopes": ["team", "personal", "groupchat"],
      "commandLists": [
        {
          "scopes": ["team", "personal", "groupchat"],
          "commands": [
            {
              "title": "debate",
              "description": "Start a multi-agent debate on a topic"
            },
            {
              "title": "gauntlet",
              "description": "Run stress-test validation"
            },
            {
              "title": "status",
              "description": "Check system status"
            },
            {
              "title": "help",
              "description": "Show available commands"
            }
          ]
        }
      ]
    }
  ],
  "permissions": ["identity", "messageTeamMembers"],
  "validDomains": ["aragora.ai", "your-api.aragora.ai"]
}

Step 4: Deploy to Teams

1. Zip manifest.json with icon files
2. Go to Teams Admin Center > "Teams apps" > "Manage apps"
3. Upload the app package
4. Approve for your organization

Step 5: Configure Azure AD Permissions (Graph API)

For advanced features like file operations, channel history, and evidence collection, configure Microsoft Graph API permissions:

1. Go to Azure Portal > "Azure Active Directory" > "App registrations"
2. Select your bot's app registration
3. Go to "API permissions" > "Add a permission" > "Microsoft Graph"

Required Application Permissions:

Permission	Type	Description	Admin Consent
ChannelMessage.Read.All	Application	Read channel messages for evidence collection	Required
Files.ReadWrite.All	Application	Upload/download files in channel SharePoint folders	Required
Team.ReadBasic.All	Application	Read team and channel metadata	Required
User.Read.All	Application	Look up user information	Required

Optional Permissions (for enhanced features):

Permission	Type	Description	Admin Consent
ChannelMember.Read.All	Application	List channel members for @mentions	Required
Chat.Read.All	Application	Read 1:1 and group chats	Required
Sites.ReadWrite.All	Application	Full SharePoint access for files	Required

4. Click "Grant admin consent for [Organization]" (requires admin)

Verify Permissions:

# Check granted permissions via Graph API
curl -X GET "https://graph.microsoft.com/v1.0/me" \
  -H "Authorization: Bearer $GRAPH_ACCESS_TOKEN"

Step 6: Configure Tenant ID (Required for Graph API)

For Graph API features, you need your Azure AD tenant ID:

1. Go to Azure Portal > "Azure Active Directory" > "Overview"
2. Copy the Tenant ID

Step 7: Configure Environment

TEAMS_APP_ID=your-app-id
TEAMS_APP_PASSWORD=your-client-secret
TEAMS_TENANT_ID=your-tenant-id  # Required for Graph API features

Feature Availability by Configuration:

Feature	Requires Tenant ID	Requires Graph Permissions
Basic messaging	No	No
Adaptive cards	No	No
File upload/download	Yes	Files.ReadWrite.All
Channel history	Yes	ChannelMessage.Read.All
Evidence collection	Yes	ChannelMessage.Read.All
User lookup	Yes	User.Read.All

Usage

In Teams:

@Aragora debate Should we adopt Kubernetes?

Adaptive Cards: Results appear as rich adaptive cards with voting buttons.

---

Zoom

Prerequisites

• Zoom account with admin access
• Access to Zoom Marketplace

Step 1: Create Zoom App

1. Go to Zoom App Marketplace
2. Choose "Chatbot" as app type
3. Fill in app information:
   • App Name: Aragora
   • Company Name: Your company
   • Category: Productivity

Step 2: Configure OAuth

1. Under "App Credentials", note:
   • Client ID
   • Client Secret
2. Add OAuth Redirect URL:

   https://your-api.aragora.ai/api/bots/zoom/oauth/callback

Step 3: Configure Chatbot

1. Under "Feature" > "Chatbot":
   • Enable chatbot
   • Set Bot JID (noted after activation)
   • Add Slash Command: /aragora
2. Add Event Subscriptions:
   • Event URL: https://your-api.aragora.ai/api/bots/zoom/events
   • Events: bot_notification

Step 4: Security

1. Under "Feature" > "Event Subscription":
   • Note the Secret Token for webhook verification
2. Under "App Credentials":
   • Note the Verification Token

Step 5: Configure Environment

ZOOM_CLIENT_ID=your-client-id
ZOOM_CLIENT_SECRET=your-client-secret
ZOOM_BOT_JID=your-bot-jid
ZOOM_SECRET_TOKEN=your-secret-token
ZOOM_VERIFICATION_TOKEN=your-verification-token

Usage

In Zoom Chat:

/aragora debate What's the best CI/CD approach?

---

Slack

Slack integration builds on existing Slack handler with enhanced bidirectional features.

Prerequisites

• Slack workspace admin access
• Existing Slack app or create new

Step 1: Configure Slack App

1. Go to your app settings
2. Under "OAuth & Permissions", add scopes:
   • chat:write
   • commands
   • files:read (for gauntlet attachments)
   • users:read
3. Under "Slash Commands", add:
   • /aragora with URL: https://your-api.aragora.ai/api/social/slack/command

Step 2: Enable Events

1. Under "Event Subscriptions":
   • Enable events
   • Request URL: https://your-api.aragora.ai/api/social/slack/events
   • Subscribe to bot events: app_mention, message.im

Step 3: Configure Environment

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_APP_TOKEN=xapp-your-app-token  # Optional, for Socket Mode

Usage

Slash Commands:

/aragora debate "Should we use TypeScript or JavaScript?"
/aragora gauntlet  # Attach a file for validation
/aragora status

Bot Mention:

@Aragora help

---

Telegram

Telegram integration enables debate and validation directly in Telegram chats.

Prerequisites

• Telegram account
• Access to @BotFather for bot creation

Step 1: Create Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts
3. Choose a name (e.g., "Aragora")
4. Choose a username (e.g., "aragora_bot")
5. Copy the Bot Token (keep this secret!)

Step 2: Configure Webhook

Set the webhook URL using the Telegram API:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-api.aragora.ai/api/bots/telegram/webhook",
    "secret_token": "your-secret-token"
  }'

Or use the token-in-URL approach (alternative):

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -d "url=https://your-api.aragora.ai/api/bots/telegram/webhook/<WEBHOOK_TOKEN>"

Step 3: Configure Environment

TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_WEBHOOK_SECRET=your-secret-token  # Optional, for X-Telegram-Bot-Api-Secret-Token verification

Step 4: Set Bot Commands (Optional)

Configure command hints in @BotFather:

/setcommands

Then send:

start - Start using Aragora
help - Show available commands
debate - Start a multi-agent debate
status - Check system status
ask - Alias for debate

Usage

Commands:

/start - Welcome message and introduction
/help - Show available commands
/debate Should we use microservices? - Start a debate
/ask Is Python better than JavaScript? - Alias for /debate
/status - Check Aragora status

Inline Buttons: After debates complete, use inline buttons to vote on outcomes.

Example Interaction:

User: /debate Should we adopt GraphQL or REST?

Aragora: Starting debate on: Should we adopt GraphQL or REST?...

I'll notify you when the AI agents reach consensus.

---

[After debate completes]

Aragora: ✅ Debate Complete

📋 Topic: Should we adopt GraphQL or REST?
🤝 Consensus: PARTIAL_AGREEMENT
📊 Confidence: 82%

[View Results] [Vote Agree] [Vote Disagree]

Features

• Bot Commands: Full slash command support
• Inline Keyboards: Interactive buttons for voting
• Callback Queries: Handle button presses
• Group Support: Works in private chats, groups, and supergroups
• Edited Messages: Handles message edits

---

WhatsApp Business

WhatsApp integration enables debate and validation directly in WhatsApp conversations.

Prerequisites

• WhatsApp Business Account
• Access to Meta for Developers
• Phone number registered with WhatsApp Business API

Step 1: Create Meta App

1. Go to Meta for Developers
2. Create a new app (type: Business)
3. Add WhatsApp product to your app
4. Note your Phone Number ID and WhatsApp Business Account ID

Step 2: Configure Webhook

1. Under WhatsApp > Configuration:
   • Webhook URL: https://your-api.aragora.ai/api/integrations/whatsapp/webhook
   • Verify Token: Generate a secure random string
   • Subscribe to events:
     • messages
     • message_status
     • messaging_postbacks

Step 3: Generate Access Token

1. Under WhatsApp > API Setup:
   • Generate a permanent access token (or use temporary for testing)
   • Grant permissions: whatsapp_business_messaging, whatsapp_business_management

Step 4: Configure Message Templates

WhatsApp requires pre-approved templates for proactive messages. Create templates for:

1. Debate Results Template (aragora_debate_result):

   *Debate Complete*
   
   Topic: {\{1\}}
   Consensus: {\{2\}}
   Confidence: {\{3\}}%
   
   View full results: {\{4\}}

2. Gauntlet Alert Template (aragora_gauntlet_alert):

   *Validation Alert*
   
   Statement: {\{1\}}
   Status: {\{2\}}
   Issues Found: {\{3\}}
   
   Details: {\{4\}}

Submit templates for review in WhatsApp Manager.

Step 5: Configure Environment

WHATSAPP_ACCESS_TOKEN=your-access-token
WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
WHATSAPP_BUSINESS_ACCOUNT_ID=your-business-account-id
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your-verify-token
WHATSAPP_PROVIDER=meta  # or 'twilio' for Twilio integration

Alternative: Twilio Integration

For Twilio WhatsApp:

WHATSAPP_PROVIDER=twilio
TWILIO_ACCOUNT_SID=your-account-sid
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_WHATSAPP_NUMBER=whatsapp:+14155238886  # Twilio sandbox or your number

Usage

Initiate a Debate:

debate: Should we migrate to cloud?

Run Gauntlet:

gauntlet: Our Q4 revenue will increase 20%

Get Help:

help

Example Interaction:

User: debate: Is remote work better than office work?

Aragora: 🎯 Starting debate...

Topic: "Is remote work better than office work?"
Agents: Claude, GPT-4, Gemini, Grok

I'll send you results when the debate concludes.

---

[After debate completes]

Aragora: ✅ *Debate Complete*

📋 Topic: Is remote work better than office work?

🤝 Consensus: PARTIAL_AGREEMENT
Both have tradeoffs; hybrid model often optimal

📊 Confidence: 78%

🗳️ Would you like to:
1. View full transcript
2. Start a follow-up debate
3. Share results

Reply with 1, 2, or 3

Features

• Interactive Lists: Use numbered replies for navigation
• Rich Messages: Formatted text with emojis for clarity
• Status Updates: Real-time notifications during long debates
• Threaded Conversations: Context maintained per conversation
• Media Support: Send documents for gauntlet analysis

Rate Limits

WhatsApp Business API has rate limits:

• 250 messages/second per phone number (tier-based)
• Template messages limited by quality rating
• Session messages unlimited within 24-hour window

---

Architecture

Bot Framework

All bots share a common framework:

aragora/bots/
├── base.py         # Common classes (BotUser, CommandContext, etc.)
├── commands.py     # Command registry and built-in commands
├── discord_bot.py  # Discord-specific implementation
├── teams_bot.py    # Teams-specific implementation
└── zoom_bot.py     # Zoom-specific implementation

Request Flow

Chat Platform → Webhook Handler → Command Registry → Execute → Response

1. Webhook Handler: Validates signatures, parses platform-specific payload
2. Command Registry: Routes to appropriate command handler
3. Execute: Runs the command (debate, gauntlet, etc.)
4. Response: Formats platform-specific response (embeds, cards, etc.)

Extending Commands

To add a custom command:

from aragora.bots.commands import get_default_registry, BotCommand
from aragora.bots.base import CommandContext, CommandResult

registry = get_default_registry()

@registry.command(
    name="custom",
    description="My custom command",
    usage="custom <args>",
)
async def handle_custom(ctx: CommandContext) -> CommandResult:
    return CommandResult(
        success=True,
        message=f"Custom response for {ctx.raw_args}",
    )

---

Troubleshooting

Discord: "Invalid Interaction"

• Verify your Public Key is correct
• Ensure Interactions Endpoint URL is accessible
• Check server logs for signature verification errors

Teams: Bot Not Responding

• Verify Messaging Endpoint is correct
• Check Azure Bot health in portal
• Ensure Teams channel is enabled

Teams: Graph API Errors (File Operations, Channel History)

• 401 Unauthorized: Verify TEAMS_TENANT_ID is set correctly
• 403 Forbidden: Check that admin consent was granted for required permissions
• 404 Not Found: Verify team_id is passed for channel-scoped operations
• Rate Limit (429): Implement exponential backoff; Teams connector handles this automatically
• File upload fails: Ensure Files.ReadWrite.All permission is granted
• Channel history empty: Ensure ChannelMessage.Read.All permission is granted

Debug Graph API token:

# Decode your token to check permissions
echo $GRAPH_TOKEN | cut -d. -f2 | base64 -d 2>/dev/null | jq .roles

Zoom: Webhook Verification Failed

• Verify Secret Token matches
• Check timestamp header is present
• Ensure webhook URL is HTTPS

Slack: Command Timeout

• Slash commands must respond within 3 seconds
• For long operations, respond with acknowledgment then use response_url
• Check Slack app Event Subscriptions are enabled

Telegram: Bot Not Responding

• Verify TELEGRAM_BOT_TOKEN is correct
• Check webhook is properly set via getWebhookInfo API
• Ensure TELEGRAM_WEBHOOK_SECRET matches the secret_token used in setWebhook
• Check server logs for secret token verification errors

WhatsApp: Webhook Verification Failed

• Verify WHATSAPP_VERIFY_TOKEN matches the token in Meta webhook configuration
• For signature errors, check WHATSAPP_APP_SECRET is correct
• Ensure webhook URL is HTTPS and publicly accessible
• Check Meta App Dashboard for webhook delivery status

General: Rate Limiting

• Commands have built-in rate limiting (10/minute per user)
• Debates have additional rate limits based on organization tier
• Check /api/bots/<platform>/status for configuration status

---

Security Considerations

1. Never commit tokens: Use environment variables
2. Verify signatures: All platforms provide signature verification
3. Use HTTPS: All webhook endpoints must be HTTPS in production
4. Limit scopes: Request only necessary permissions
5. Audit logs: All bot commands are logged for audit

---

Support

• Report issues: GitHub Issues
• Documentation: https://docs.aragora.ai
• Discord: Aragora Community