8.3 KiB
Telegram Setup
This guide walks you through connecting OpenACP to Telegram. OpenACP uses a Telegram group with Topics enabled — each coding session gets its own topic thread for an organized, isolated workspace.
Prerequisites:
- A Telegram group (any size)
- Topics enabled — Group Settings → Edit → Topics
- Bot is admin with "Manage Topics" permission — Group Settings → Administrators
If these aren't set up when OpenACP first starts, it will send instructions to your group's General topic and keep retrying automatically.
Prerequisites
- A Telegram account
- OpenACP installed:
npm install -g @openacp/cli - At least one ACP agent installed (e.g.,
claude-agent-acp)
Step 1: Create a Bot via BotFather
- Open Telegram and search for @BotFather, or click that link.
- Send the command
/newbot. - BotFather will ask for a name — enter a display name (e.g.,
My OpenACP Bot). - BotFather will then ask for a username — enter a unique username ending in
bot(e.g.,myopenacp_bot). - BotFather replies with your bot token. It looks like:
123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - Copy and save this token somewhere safe. You will need it in Step 6.
Important: Your bot token is a secret. Anyone with this token can control your bot. Never share it publicly or commit it to version control.
Step 2: Create a Group with Topics Enabled
OpenACP requires a Telegram group with the Topics feature enabled. Topics create thread-like channels — one per coding session.
- In Telegram, tap the compose icon and select New Group.
- Add your bot as a member (search for its username).
- Give the group a name (e.g.,
OpenACP) and create it. - Open the group → tap the group name at the top → Edit (pencil icon).
- Scroll down and enable Topics.
- Save the changes.
Step 3: Add the Bot as Admin
The bot must be an administrator with the following permissions to manage topics and send messages:
- Open the group → tap the group name → Administrators.
- Tap Add Administrator.
- Search for your bot by username and select it.
- Make sure these permissions are enabled:
- Manage Topics — required to create and rename session topics
- Send Messages — required to send responses
- Delete Messages — recommended for cleanup
- Tap Save.
OpenACP validates that the bot is an administrator during setup. If it is not, setup will fail with an error and prompt you to fix it.
Step 4: Get the Chat ID
The Chat ID is the unique numeric identifier for your group. You need it for the config.
Option A: Use the OpenACP setup wizard (recommended)
The interactive wizard auto-detects your Chat ID. Run:
openacp
When prompted for the Chat ID, send any message in your group. The wizard polls the Telegram API for updates and reports the group it sees:
Group detected: My OpenACP Bot (-1001234567890)
Option B: Use @RawDataBot
Forward any message from your group to @RawDataBot. It replies with the raw update JSON, which includes "chat": {"id": -1001234567890, ...}. The Chat ID is the negative number starting with -100.
Option C: Use the Telegram API directly
https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
Replace <YOUR_TOKEN> with your bot token. Send a message in the group first, then open this URL. Look for "chat": {"id": ...} in the response.
Step 5: Configure OpenACP
Edit ~/.openacp/config.json and fill in the Telegram section (see the full configuration reference for all available options):
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"chatId": -1001234567890,
"notificationTopicId": null,
"assistantTopicId": null
}
}
}
| Field | Description |
|---|---|
enabled |
Set to true to activate the Telegram adapter |
botToken |
The token from BotFather (Step 1) |
chatId |
The group's Chat ID — negative number starting with -100 (Step 4) |
notificationTopicId |
Leave null — OpenACP creates this topic on first start |
assistantTopicId |
Leave null — OpenACP creates this topic on first start |
Tip: You can also run
openacp(the interactive setup wizard) instead of editing the file manually. The wizard validates your token and auto-detects the Chat ID.
Step 6: Start OpenACP and Test
Start OpenACP:
openacp start
Expected output:
[info] Telegram adapter started
[info] Notification topic created (id: 2)
[info] Assistant topic created (id: 3)
[info] OpenACP ready
Open your Telegram group. You should see two new topics appear automatically.
To create your first coding session, use the /new command in the group's General topic or the Assistant topic:
/new claude my-project
OpenACP creates a new topic thread for this session.
Step 7: System Topics (Auto-Created on First Start)
On first start, OpenACP automatically creates two system topics in your group:
| Topic | Purpose |
|---|---|
Notifications (📋 Notifications) |
Receives completion summaries, error alerts, and permission request notifications with deep links back to the relevant session topic |
Assistant (🤖 Assistant) |
An always-on AI helper session. Send questions here to get guidance on using OpenACP, creating sessions, or troubleshooting |
The topic IDs are saved to your config automatically:
{
"channels": {
"telegram": {
"notificationTopicId": 2,
"assistantTopicId": 3
}
}
}
On subsequent restarts, OpenACP reuses these existing topics rather than creating new ones.
Step 8: Session Topics
Each /new command creates a dedicated forum topic for that coding session:
- Real-time streaming — agent responses appear as the model generates them, with message edits batched at ~1-second intervals to avoid Telegram rate limits.
- Auto-naming — after the first prompt, the topic is renamed to a short 5-word summary of the task (e.g.,
Add login form to app). - Prompt queue — send multiple messages while the agent is processing; they are queued and processed in order.
- Permission buttons — when the agent needs approval to run a command or modify a file, inline Allow / Always Allow / Reject buttons appear in the topic.
- Skill commands — the agent publishes available skills as inline buttons, pinned at the top of the topic.
- Viewer links — if the tunnel feature is enabled, tool calls include clickable links to an in-browser file or diff viewer.
When the session ends, the topic stays open for reference. Use /cancel to cancel a running session.
Environment Variables
You can pass credentials via environment variables instead of editing the config file. This is useful in scripts or CI environments:
export OPENACP_TELEGRAM_BOT_TOKEN="123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export OPENACP_TELEGRAM_CHAT_ID="-1001234567890"
openacp start
| Variable | Config path |
|---|---|
OPENACP_TELEGRAM_BOT_TOKEN |
channels.telegram.botToken |
OPENACP_TELEGRAM_CHAT_ID |
channels.telegram.chatId |
Environment variables take precedence over values in config.json.
Troubleshooting
Bot is not responding
- Confirm the bot is added to the group and is an administrator.
- Verify
enabled: truein the config. - Check
~/.openacp/logs/for error messages.
"Chat must be a group" error
- Make sure you are using a group (not a channel). Channels are not supported.
- If the group was just created, wait a moment and try again.
Topics not appearing after first start
- If OpenACP cannot create topics, it sends a message to the group's General topic with instructions.
- Follow the instructions in that message: enable Topics and/or grant the bot "Manage Topics" permission.
- OpenACP retries automatically every 30 seconds — no need to restart.
Chat ID is not detected
- Make sure you sent a message in the group after adding the bot.
- Press
min the setup wizard to enter the Chat ID manually.
For more detailed troubleshooting, see Telegram Issues.