Telegram Bot Setup

Receive instant permission approval requests on Telegram. Approve or deny agent actions from anywhere.

Overview

The Agent OTP Telegram bot sends you notifications when your AI agents request permissions that need human approval. You can approve or deny requests directly from Telegram.

Setup Instructions

Step 1: Start the Bot

1. Open Telegram and search for @AgentOTPBot
2. Click Start to begin the conversation
3. The bot will greet you with a welcome message

Step 2: Link Your Account

1. Generate a link code using the CLI:

docker compose exec api bun run cli telegram:link-code

2. Copy the link code shown
3. Send the code to the Telegram bot: /link YOUR_CODE

Step 3: Test the Connection

1. Send a test notification using the CLI:

docker compose exec api bun run cli telegram:test

2. You should receive a test message in Telegram within seconds

Receiving Approval Requests

When an agent requests a permission that needs approval, you'll receive a message like this:

🔐 Permission Request

Agent: invoice-bot
Action: email.send
To: client@example.com
Subject: Invoice #12345
Reason: Sending monthly invoice to client

Requested scope:
• Max emails: 1
• Attachment: Yes (invoice.pdf)

Expires in: 4:32

[✅ Approve]  [❌ Deny]  [ℹ️ Details]

Available Actions

• Approve - Grant the permission and issue a token
• Deny - Reject the request with an optional reason
• Details - See full request context and scope

Bot Commands

Notification Settings

Configure which notifications you receive:

/settings

📱 Notification Settings

• All requests: ✅ Enabled
• Auto-approved: ❌ Disabled
• Denied by policy: ❌ Disabled
• Token used: ❌ Disabled
• Token expired: ✅ Enabled

• Quiet hours: 10 PM - 7 AM
• Timezone: America/New_York

[Edit Settings]

Quiet Hours

During quiet hours, notifications are batched and delivered when quiet hours end. Urgent requests (expiring soon) will still notify immediately.

Quick Replies

Use quick replies for faster decisions:

• /approve PERM_ID - Approve a specific request
• /deny PERM_ID reason - Deny with a reason
• /approve-all AGENT - Approve all pending for an agent

Group Notifications

For team settings, add the bot to a Telegram group:

1. Add @AgentOTPBot to your team group
2. Link the group using the CLI:

   docker compose exec api bun run cli telegram:link-group

3. Configure which team members can approve requests

Troubleshooting

Not Receiving Notifications

1. Check that your account is linked: /status
2. Verify Telegram bot token is configured in your .env file
3. Check quiet hours settings
4. Ensure Telegram notifications are not muted

Link Code Not Working

• Link codes expire after 5 minutes - generate a new one
• Make sure you're typing the exact code shown
• Check for extra spaces before/after the code

Buttons Not Responding

• The request may have expired - check the expiry time
• Someone else may have already responded (in groups)
• Try using the command: /approve PERM_ID

Security Considerations

• Keep your Telegram account secure - Enable two-factor authentication
• Don't share screenshots - They may contain sensitive request details
• Review requests carefully - Check the scope and context before approving
• Use groups wisely - Only add trusted team members

Alternative Notification Channels

Besides Telegram, you can also receive notifications via:

• Email - Good for async approval workflows
• Slack - For team-based approvals
• Web Dashboard - Real-time in-browser notifications
• Webhooks - For custom integrations

See Also

• Quick Start Guide
• Understanding Permissions
• Policy Best Practices