The Telegram channel gateway turns your Telegram bot into a full conversational interface for Polpo. Send messages, run commands, approve tasks, and manage your project — all from Telegram.
This page covers interactive messaging (talking to Polpo via Telegram). For one-way notification delivery (Polpo sending you alerts), see Telegram Notifications. Setup
-
Create a Telegram bot via @BotFather and save the bot token.
-
Get your chat ID — message the bot, then call:
https://api.telegram.org/bot{TOKEN}/getUpdates
chat.id in the response.
-
Configure the gateway in
polpo.json:
{
"settings": {
"notifications": {
"channels": {
"telegram": {
"type": "telegram",
"botToken": "${TELEGRAM_BOT_TOKEN}",
"chatId": "-1001234567890",
"gateway": {
"enableInbound": true,
"dmPolicy": "allowlist",
"allowFrom": ["YOUR_TELEGRAM_USER_ID"]
}
}
}
}
}
}
-
Start Polpo — the gateway activates automatically:
Gateway Configuration
The gateway object on a notification channel enables inbound messaging:
| Field | Type | Default | Description |
|---|
enableInbound | boolean | false | Enable the conversational gateway |
dmPolicy | string | "allowlist" | Who can message the bot: open, allowlist, pairing, disabled |
allowFrom | string[] | [] | Telegram user IDs or peer IDs allowed to message. Use ["*"] for everyone |
sessionIdleMinutes | number | 60 | Auto-reset session after idle period |
DM Policies
Control who can interact with your bot:
| Policy | Behavior |
|---|
open | Anyone can message the bot |
allowlist | Only users in allowFrom or the dynamic allowlist can message |
pairing | Unknown users get a pairing code. An admin approves the code to grant access |
disabled | Inbound messages are silently ignored |
Pairing Flow
With "dmPolicy": "pairing", new users are onboarded securely:
- Unknown user messages the bot
- Bot replies with a 6-character pairing code (e.g.,
ABC123)
- An admin approves the code via:
- Telegram:
/pair ABC123
- REST API:
POST /api/v1/projects/:id/peers/pair with {"code": "ABC123"}
- TUI or Web UI
- The user is added to the allowlist and can now chat freely
Pairing codes expire after 1 hour. Max 3 pending codes per channel.
Slash Commands
Send these commands as Telegram messages:
| Command | Description |
|---|
/help | Show all available commands |
/status | Project status — task counts, active agents, connected peers |
/tasks | List tasks with status |
/missions | List missions |
/agents | List agents with active/idle status |
/approve [ID] | List pending approvals, or approve a specific one |
/reject ID [reason] | Reject an approval with feedback |
/new | Reset your conversation session |
/pair CODE | Approve a pairing request (admin only) |
Free-Text Chat
Any message that isn’t a slash command is routed to Polpo’s agentic completions loop. You can:
- Ask questions about your project
- Create tasks and missions
- Get status updates
- Request code changes
You: Create a task to fix the login validation bug in src/auth/login.ts
Polpo: Created task "Fix login validation bug" and assigned it to backend-dev.
The agent will look at src/auth/login.ts and fix the validation logic.
/new.
Interactive Approvals
When an approval gate is triggered, the bot sends a message with Approve and Reject inline buttons:
- Approve — immediately approves the pending request
- Reject — prompts for feedback. Your next message is captured as rejection feedback and the task retries with your notes
This works alongside the slash commands (/approve, /reject) — use whichever is more convenient.
Multi-User Support
The gateway supports multiple users on the same bot:
- Peer identity — each user is identified by their Telegram user ID (
telegram:{userId})
- Session isolation — each user gets their own conversation thread
- Presence tracking — Polpo tracks who’s currently active
- Identity linking — link a Telegram identity to a WhatsApp identity (or any other channel) to share sessions across channels
Peer Management API
Manage peers via the REST API:
| Method | Path | Description |
|---|
GET | /peers | List known peers |
GET | /peers/presence | Online peers and activity |
GET | /peers/allowlist | Current allowlist |
POST | /peers/allowlist | Add peer to allowlist |
DELETE | /peers/allowlist/:id | Remove from allowlist |
POST | /peers/pair | Approve a pairing code |
POST | /peers/link | Link two peer identities |
Example Configurations
Personal Use (open)
{
"gateway": {
"enableInbound": true,
"dmPolicy": "open"
}
}
Team Use (allowlist)
{
"gateway": {
"enableInbound": true,
"dmPolicy": "allowlist",
"allowFrom": ["123456789", "987654321"]
}
}
Secure Team (pairing)
{
"gateway": {
"enableInbound": true,
"dmPolicy": "pairing",
"allowFrom": ["123456789"],
"sessionIdleMinutes": 30
}
}
123456789) is pre-authorized and can approve pairing codes for new team members.
With "dmPolicy": "open", anyone who discovers your bot can interact with it and control your agents. Use allowlist or pairing for any non-personal deployment.
