Skip to content

Integrations

Aegis integrates with multiple external services for communication, development, and monetization.

Communication

Discord

Primary communication channel for status updates, notifications, and autonomous task reception.

  • Guild ID: 1454722052777836546
  • Channels: #general, #tasks, #alerts, #journal, #decisions, #logs, #scratchpad
  • Features: Task polling, message posting, daily updates
  • MCP Tools: discord_send_message, discord_login

Telegram

Time-sensitive notifications and system health alerts.

  • Chat ID: 1275129801
  • Use Cases: Critical alerts, error escalations, deployment notifications
  • MCP Tools: send_message, get_updates

WhatsApp

Two-way mobile command and control via Vonage Messages API.

  • WABA Number: +44 7441 443388
  • Features: Claude sessions, system commands, knowledge graph queries, 3D generation
  • Commands: task:, c:, status, deploy, logs, morning, evening
  • Code: aegis/whatsapp/, aegis/dashboard/routes/vonage.py

Email

Gmail integration via Google Workspace for email triage and management.

  • Account: aegis@richardbankole.com
  • Features: Email triage, classification, search, send
  • MCP Tools: gmail_search, gmail_send, gmail_modify

Development

GitHub

Version control, PR management, and issue tracking.

  • Repository: aegis-agent/aegis-core
  • Features: PR reviews, issue management, file operations, webhooks
  • MCP Tools: create_pull_request, create_issue, get_file_contents
  • Workflow: Feature branches, conventional commits, Claude co-authoring

Google Workspace

Complete Google Workspace integration (Gmail, Calendar, Drive, Sheets).

  • Account: aegis@richardbankole.com
  • Services: Gmail, Calendar, Drive, Sheets
  • Features: Email triage, calendar sync, file storage, spreadsheet operations
  • MCP Tools: calendar_list_events, drive_create_file, sheets_update_values

Monetization

Stripe

Payment processing and billing infrastructure for API monetization.

  • Features: Customer management, invoicing, subscriptions, webhooks
  • Pricing Models: Usage-based, outcome-based, subscription-based
  • Code: aegis/monetization/billing.py, aegis/monetization/
  • Database: billing_transactions, stripe_customers, stripe_webhook_events

Integration Architecture

MCP Server Configuration

All MCP servers are configured in ~/.claude.json:

{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["/home/agent/mcp-servers/discord/dist/index.js"],
      "env": {"DISCORD_BOT_TOKEN": "..."}
    },
    "telegram": {
      "command": "node",
      "args": ["/home/agent/mcp-servers/telegram-mcp-server/dist/index.js"],
      "env": {"TELEGRAM_BOT_TOKEN": "..."}
    },
    "google-workspace": {
      "command": "node",
      "args": ["/home/agent/mcp-servers/google-workspace/dist/index.js"],
      "env": {"GOOGLE_APPLICATION_CREDENTIALS": "~/.secure/google-workspace-credentials.json"}
    },
    "github": {
      "command": "node",
      "args": ["/home/agent/mcp-servers/github/dist/index.js"],
      "env": {"GITHUB_TOKEN": "..."}
    },
    "vonage": {
      "command": "node",
      "args": ["/home/agent/mcp-servers/vonage/dist/index.js"],
      "env": {
        "VONAGE_API_KEY": "...",
        "VONAGE_API_SECRET": "...",
        "VONAGE_APPLICATION_ID": "...",
        "VONAGE_PRIVATE_KEY_B64": "..."
      }
    }
  }
}

Communication Flow

┌─────────────────────────────────────────────┐
│                    User                     │
└───┬─────────────────────────────────────┬───┘
    │                                     │
    │ Mobile                              │ Desktop
    │                                     │
┌───▼────────┐                    ┌───────▼──────┐
│  WhatsApp  │                    │   Discord    │
│   Vonage   │                    │  Telegram    │
└───┬────────┘                    └───────┬──────┘
    │                                     │
    │ Webhooks                            │ MCP
    │                                     │
┌───▼─────────────────────────────────────▼───┐
│         Aegis Core (FastAPI + MCP)          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ WhatsApp │  │ Discord  │  │ Telegram │  │
│  │ Handler  │  │  Poller  │  │  Alerts  │  │
│  └──────────┘  └──────────┘  └──────────┘  │
└─────────────────────────────────────────────┘

Data Storage

All integrations use PostgreSQL for caching and state:

Integration Tables
Discord discord_tasks, discord_sessions
WhatsApp whatsapp_sessions, whatsapp_messages
Email email_cache
Calendar calendar_cache
Stripe billing_transactions, stripe_customers, stripe_webhook_events

Authentication

Service Method Storage Location
Discord Bot Token ~/.claude.json (mcpServers.discord.env.DISCORD_BOT_TOKEN)
Telegram Bot Token ~/.claude.json (mcpServers.telegram.env.TELEGRAM_BOT_TOKEN)
WhatsApp Vonage JWT Environment vars (VONAGE_PRIVATE_KEY_B64)
Google Workspace Service Account ~/.secure/google-workspace-credentials.json
GitHub Personal Access Token ~/.claude.json (mcpServers.github.env.GITHUB_TOKEN)
Stripe API Key Environment vars (STRIPE_API_KEY)

Common Patterns

Daily Routines

Both morning and evening routines leverage integrations:

# Morning routine
1. Discord: Post to #journal
2. Email: Check unread count, triage if needed
3. Calendar: Sync today's events
4. WhatsApp: Send morning summary (if requested)
5. Beads: Get pending tasks

# Evening routine
1. Discord: Post summary to #journal
2. Calendar: Preview tomorrow's events
3. Email: Final triage check
4. WhatsApp: Send evening summary (if requested)
5. Beads: Update task statuses

Error Escalation (Three-Strike Protocol)

# Strike 1: Retry
# Strike 2: Switch to local model
# Strike 3: Escalate
1. Discord: Post to #alerts
2. Telegram: Send critical alert
3. WhatsApp: Notify authorized users
4. Journal: Document error context

Task Delegation

# User posts in Discord #tasks
1. Discord: Task poller detects message
2. Beads: Create task if multi-session
3. Claude: Start session
4. Discord: Post acknowledgment

# User sends WhatsApp message
1. Vonage: Webhook receives message
2. WhatsApp: Parse intent
3. Claude: Start session if needed
4. WhatsApp: Send response

Best Practices

  1. Authentication: Store credentials in ~/.secure/ or ~/.claude.json, never in code
  2. Error Handling: Always wrap integration calls in try/except
  3. Rate Limits: Respect API quotas, implement exponential backoff
  4. Caching: Cache frequently accessed data in PostgreSQL
  5. Logging: Log all integration events to structlog
  6. Security: Verify webhook signatures, authorize users
  7. Graceful Degradation: Handle service outages without crashing

Troubleshooting

MCP Server Not Starting

# Check Claude logs
tail -f ~/.claude/logs/main.log

# Test MCP server manually
node /home/agent/mcp-servers/discord/dist/index.js

# Verify configuration
cat ~/.claude.json | jq '.mcpServers'

Authentication Failures

# Discord
echo $DISCORD_BOT_TOKEN

# Vonage
echo $VONAGE_APPLICATION_ID
cat ~/.secure/vonage-private-key.pem

# Google Workspace
cat ~/.secure/google-workspace-credentials.json | jq .

# GitHub
ssh -T git@github.com

Webhook Not Received

# Check Traefik routing
docker logs aegis-traefik | grep vonage

# Test webhook endpoint
curl -X POST https://aegis.rbnk.uk/api/vonage/whatsapp/inbound \
  -H "Content-Type: application/json" \
  -d '{"message_uuid": "test", "from": "447490195079", "text": "test"}'

# Check FastAPI logs
docker logs aegis-dashboard

Next Steps