Web UI Setup

ThePopeBot ships with a built-in Web UI that provides a chat interface for interacting with your agents. The Web UI is already configured when you run the development server, but let us look at how to customize it.

Accessing the Web UI

After starting the server with npm run dev, navigate to http://localhost:3000 in your browser. The interface includes:

A chat panel for real-time conversation with your agents
An agent selector to switch between available agents
A history panel showing past conversations
A settings panel for runtime configuration

Customizing the Web UI

You can configure the Web UI through config/web.yaml:

web:
  port: 3000
  title: "My Agent Dashboard"
  theme: "dark"
  features:
    history: true
    agentSelector: true
    fileUpload: true
    codeHighlighting: true
  auth:
    enabled: false
    provider: "basic"  # basic, oauth, or custom

To enable authentication for production use:

web:
  auth:
    enabled: true
    provider: "oauth"
    oauth:
      clientId: "${OAUTH_CLIENT_ID}"
      clientSecret: "${OAUTH_CLIENT_SECRET}"
      authorizeUrl: "https://your-provider.com/authorize"

Telegram Bot Integration

Telegram is one of the most popular channels for interacting with ThePopeBot. Here is how to set it up.

Step 1: Create a Telegram Bot

Open Telegram and search for @BotFather
Send /newbot and follow the prompts
Copy the API token you receive

Step 2: Configure the Adapter

Add the Telegram configuration to your .env file:

TELEGRAM_BOT_TOKEN=your-bot-token-here
TELEGRAM_ALLOWED_USERS=user_id_1,user_id_2
TELEGRAM_DEFAULT_AGENT=default

Then enable the Telegram adapter in config/channels.yaml:

channels:
  telegram:
    enabled: true
    token: "${TELEGRAM_BOT_TOKEN}"
    allowedUsers: "${TELEGRAM_ALLOWED_USERS}"
    defaultAgent: "default"
    commands:
      /start: "Welcome message and help"
      /agent: "Switch active agent"
      /reset: "Clear conversation history"

Step 3: Start the Bot

The Telegram adapter starts automatically with the main server:

npm run dev
# [ThePopeBot] Telegram bot connected as @YourBotName

Now you can message your bot on Telegram, and it will respond using the configured agent.

Handling Rich Messages

The Telegram adapter supports rich formatting:

// The agent can send formatted responses
{
  format: 'telegram',
  text: '*Bold text* and `inline code`',
  parseMode: 'Markdown',
  replyMarkup: {
    inlineKeyboard: [[
      { text: 'Approve', callbackData: 'approve_pr_42' },
      { text: 'Reject', callbackData: 'reject_pr_42' }
    ]]
  }
}

Webhook Configuration

Webhooks allow external services to trigger your agents. This is essential for integrating with GitHub, GitLab, Jira, and other platforms.

Setting Up a Webhook Endpoint

Configure webhooks in config/channels.yaml:

channels:
  webhook:
    enabled: true
    endpoints:
      github:
        path: "/webhook/github"
        secret: "${GITHUB_WEBHOOK_SECRET}"
        agent: "reviewer"
        events:
          - pull_request.opened
          - pull_request.synchronize
          - issue_comment.created

      custom:
        path: "/webhook/custom"
        secret: "${CUSTOM_WEBHOOK_SECRET}"
        agent: "default"

Processing Webhook Events

When a GitHub PR is opened, the webhook adapter receives the payload, extracts the relevant information, and routes it to the appropriate agent:

// Example webhook event transformation
const event: AgentEvent = {
  source: 'webhook:github',
  type: 'pull_request.opened',
  message: `New PR #${payload.number}: ${payload.title}`,
  metadata: {
    repo: payload.repository.full_name,
    prNumber: payload.number,
    author: payload.sender.login,
    diff: payload.pull_request.diff_url,
  },
};

Testing Webhooks Locally

Use a tool like ngrok to expose your local server for webhook testing:

ngrok http 3000
# Forwarding: https://abc123.ngrok.io -> http://localhost:3000

Then configure your GitHub repository to send webhooks to https://abc123.ngrok.io/webhook/github.

Cron Job Scheduling

ThePopeBot can run agents on a schedule using cron expressions. This is useful for periodic tasks like daily code quality reports, dependency updates, or monitoring checks.

Configuring Cron Jobs

Add cron schedules in config/channels.yaml:

channels:
  cron:
    enabled: true
    jobs:
      daily-report:
        schedule: "0 9 * * 1-5"  # 9 AM on weekdays
        agent: "reporter"
        message: "Generate the daily code quality report"
        output:
          - channel: telegram
            chatId: "${TEAM_CHAT_ID}"

      dependency-check:
        schedule: "0 0 * * 0"  # Midnight on Sundays
        agent: "security"
        message: "Scan all dependencies for vulnerabilities"
        output:
          - channel: webhook
            url: "${SLACK_WEBHOOK_URL}"

      health-check:
        schedule: "*/30 * * * *"  # Every 30 minutes
        agent: "monitor"
        message: "Check system health and report anomalies"

Cron Expression Reference

Expression	Description
`* * * * *`	Every minute
`0 * * * *`	Every hour
`0 9 * * 1-5`	9 AM weekdays
`0 0 * * 0`	Midnight on Sundays
`/15 * * *`	Every 15 minutes

Channel-Specific Best Practices

Web UI

Enable authentication in production
Use WebSocket connections for real-time responses
Implement file upload for document analysis tasks

Always restrict access with allowedUsers
Use inline keyboards for interactive workflows
Keep responses under 4096 characters (Telegram limit)
Implement /cancel to stop long-running tasks

Webhooks

Always validate webhook signatures for security
Use idempotency keys to prevent duplicate processing
Implement retry logic for failed deliveries
Log all incoming payloads for debugging

Cron Jobs

Use descriptive job names for easy monitoring
Set appropriate timeouts for long-running tasks
Route output to the right notification channel
Monitor job execution history for failures

Multi-Channel Interaction