Code from Your Phone: The Complete Guide to OpenACP with Telegram

Picture this: you are on a bus heading home from work when your monitoring system alerts you to a bug in production. Normally, you would have to wait until you get to your desk, open your laptop, fire up your terminal, and start debugging. But with OpenACP and Telegram, you pull out your phone, open the Telegram app, type a message describing the issue, and within seconds an AI coding agent on your development machine starts investigating. You watch the agent's analysis stream in real time on your phone screen. It finds the bug, proposes a fix, and asks for permission to apply it. You tap "Approve." The fix is applied. You review the diff right in Telegram. Crisis averted, all from your phone.

This is not a futuristic fantasy -- it is how thousands of developers work today with OpenACP and Telegram. In this comprehensive guide, we will cover everything you need to know about using OpenACP with Telegram, from creating your first bot to mastering advanced features like voice messages, forum topics, and session management.

Why Telegram?

OpenACP supports three messaging platforms -- Telegram, Discord, and Slack -- but Telegram consistently delivers the best experience. Here is why:

• Forum topics -- Telegram groups can organize conversations into forum topics, which OpenACP uses to create separate threads for each coding session. This is the killer feature. Each AI agent session gets its own topic with a descriptive name, making it trivial to manage multiple concurrent sessions.
• Voice messages -- Telegram's native voice message feature integrates directly with OpenACP. Record a voice message describing what you want, and OpenACP transcribes it and sends it to your AI agent. No typing required. This is a game-changer for mobile use.
• Real-time streaming -- Telegram's message editing capabilities allow OpenACP to stream agent responses in real time. You see the agent's output appear progressively, just like watching it type in a terminal.
• Cross-platform -- Telegram runs on iOS, Android, desktop (Windows, macOS, Linux), and the web. Your coding sessions are accessible from literally any device.
• Free and fast -- creating a Telegram bot is completely free, takes two minutes, and the API has generous rate limits.
• Rich formatting -- Telegram supports markdown, code blocks, inline code, and syntax highlighting, all of which OpenACP uses to render agent output beautifully.
• No workspace limits -- unlike Slack's free tier which limits message history, Telegram keeps all messages forever at no cost.

Creating a Telegram Bot with BotFather

Before you can use OpenACP with Telegram, you need to create a Telegram bot. This is done through BotFather, Telegram's official bot creation service. Here is a detailed walkthrough:

Step 1: Find BotFather

Open Telegram on any device and search for @BotFather. Make sure you select the verified account (it has a blue checkmark). BotFather is the master bot that creates and manages all other Telegram bots. It is maintained by Telegram themselves, so it is always available and secure.

Step 2: Create a New Bot

Send the command /newbot to BotFather. It will ask you two questions:

1. Display name -- this is the name that appears in chats. Choose something descriptive like "My Code Agent" or "OpenACP Dev Bot". You can change this later.
2. Username -- this must be unique across all of Telegram and must end with "bot". For example: my_openacp_dev_bot or johns_code_agent_bot. You cannot change this later, so choose carefully.

Step 3: Save Your Token

After creating the bot, BotFather responds with an API token. It looks something like:

7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This token is your bot's password. Anyone with this token can control your bot, so treat it like a secret. Copy it to a secure location. You will paste it into OpenACP's setup wizard in a moment.

Step 4: Configure Bot Settings (Optional but Recommended)

While you are in BotFather, there are a few optional settings that improve the experience:

• Send /setprivacy and select your bot, then choose "Disable". This allows the bot to read all messages in a group, not just commands that start with /. This is important because you want to send natural language messages to your AI agent.
• Send /setdescription and add a description like "AI coding agent powered by OpenACP. Send messages to interact with your coding agents remotely."
• Send /setuserpic and upload a profile picture for your bot. The OpenACP logo or a custom avatar makes it easier to identify in your chat list.

Setting Up the Telegram Group

For the best experience, you should create a dedicated Telegram group for OpenACP. Here is why and how:

Why a Group?

While you can use OpenACP in a direct message with the bot, using a group unlocks forum topics -- the feature that makes Telegram the best platform for OpenACP. Forum topics let each coding session live in its own thread, with its own name and its own history. Without forum topics, all your sessions would be in a single conversation, which gets messy fast.

Creating the Group

1. In Telegram, create a new group. You can add just yourself and the bot for now.
2. Go to the group settings (tap the group name at the top).
3. Look for "Topics" or "Forum" and enable it. On desktop, this is under "Group Type". On mobile, it is usually in the group settings menu.
4. Make your bot an admin of the group. This gives it the permissions it needs to create topics, send messages, and manage sessions.

Once the group is set up with forum topics enabled and the bot added as admin, you are ready to connect it to OpenACP.

Connecting Telegram to OpenACP

Now connect everything together. If you have not installed OpenACP yet, run:

npm install -g @openacp/cli
openacp

The setup wizard will ask you to choose a platform. Select Telegram. It will then ask for your bot token -- paste the token you received from BotFather. Next, it asks for the group ID (the wizard can auto-detect this if you send a message in the group while the wizard is running). Finally, select your workspace and agent, and you are connected.

Alternatively, if you have already run the wizard for a different platform and want to switch to Telegram, you can edit your configuration file directly:

{
  "platform": "telegram",
  "telegram": {
    "token": "7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "groupId": -1001234567890
  }
}

The group ID is a negative number that starts with -100 for supergroups (which forum-enabled groups are). The wizard typically auto-detects this, but you can also find it by adding the @userinfobot to your group temporarily and checking the chat ID.

Forum Topics: Your Session Organizer

Forum topics are the backbone of the Telegram experience. Every time you start a new coding session, OpenACP creates a new forum topic in your group. The topic serves as the isolated conversation space for that session. Here is how it works:

When you send a message in the "General" topic or create a new topic, OpenACP creates a new agent session. The session is bound to that topic. All messages in that topic go to the same agent session, and all agent responses appear in that topic. You can have dozens of topics running simultaneously, each with a different coding task.

Topics are auto-named based on the conversation content. If you start a session by asking "Refactor the authentication module to use JWT tokens," the topic might be automatically named "Auth Module JWT Refactoring." This makes it easy to find sessions later and understand what each one is about at a glance.

You can also manually name topics when creating them, pin important topics, and close topics when a session is complete. Telegram's built-in topic management features all work seamlessly with OpenACP.

Real-Time Streaming Responses

One of the most satisfying aspects of using OpenACP with Telegram is watching responses stream in real time. When you send a message to your AI agent, you do not stare at a blank screen waiting for a complete response. Instead, you see the agent's response building character by character, just like watching someone type.

Technically, this works by exploiting Telegram's message editing capability. OpenACP sends an initial message and then rapidly edits it as the agent produces more output. The edit frequency is carefully tuned to stay within Telegram's rate limits while providing a smooth streaming experience. Typically, the message updates every 500 milliseconds to one second, which is fast enough to feel real-time without hitting rate limits.

For code output, OpenACP formats responses with proper Telegram markdown. Code blocks get triple-backtick formatting with language-specific syntax highlighting where available. Inline code uses single backticks. Bold and italic text is preserved. Links are clickable. The result is a reading experience that is nearly as good as a dedicated IDE, right in your messaging app.

Permission Buttons: Approve or Deny in One Tap

AI coding agents frequently need to perform actions that require your approval: writing files, executing shell commands, making network requests, or modifying configuration. In a terminal, these permission requests appear as text prompts that you respond to by typing "y" or "n". In OpenACP with Telegram, they appear as inline keyboard buttons.

When an agent wants to perform an action, you see a message like:

The agent wants to execute: npm install express

[Approve] [Deny]

You tap "Approve" to allow the action or "Deny" to block it. The button response is instant and the agent continues immediately. This is particularly powerful on mobile because tapping a button is much faster than typing a response. You can approve a dozen actions while walking down the street, keeping your AI agent productive without breaking stride.

Permission control is not just a convenience feature -- it is a security feature. It ensures that your AI agent never performs a potentially dangerous action without your explicit approval. You maintain full control over what happens to your codebase, even when controlling the agent remotely from your phone.

Voice Messages: Talk to Your Code

Perhaps the most innovative feature of OpenACP's Telegram integration is voice message support. Telegram has native voice messaging -- press and hold the microphone button to record, release to send. OpenACP intercepts these voice messages, transcribes them using Groq's speech-to-text API (which is free), and sends the transcribed text to your AI agent.

This sounds simple, but the implications are profound. You can literally speak your coding instructions. "Look at the user authentication module and find any SQL injection vulnerabilities." "Create a new REST endpoint for the payment webhook. It should validate the signature, parse the body, and update the order status." "Refactor the database connection pool to use a singleton pattern and add proper error handling."

Voice input is especially valuable in these scenarios:

• Mobile use -- typing long, detailed instructions on a phone keyboard is slow and error-prone. Speaking them is natural and fast.
• Complex requirements -- when you need to explain a nuanced requirement, speaking is often clearer than typing. You can describe architectural decisions, business logic, and edge cases more naturally in speech.
• Hands-busy situations -- cooking, walking, driving (safely parked!), or exercising. You can interact with your AI coding agent whenever you have a thought, without needing your hands free.
• Accessibility -- for developers with conditions that make typing difficult, voice input provides an alternative interaction mode.

The speech-to-text transcription is powered by Groq, which offers fast, accurate transcription for free. The transcription typically takes less than a second, even for long voice messages. OpenACP shows you the transcription before sending it to the agent, so you can verify it was understood correctly.

On the other direction, OpenACP can also generate voice responses using Edge TTS (text-to-speech), which is also free. This is useful for accessibility or for situations where you want to listen to the agent's response rather than read it. However, for code-heavy responses, text is generally more practical than audio.

Auto-Naming Sessions

When OpenACP creates a new forum topic for a session, it automatically generates a descriptive name based on the conversation content. This happens after the first few messages, once OpenACP has enough context to understand what the session is about.

Auto-naming uses the AI agent's own understanding of the conversation to generate a concise, descriptive title. Examples of auto-generated topic names:

• "Auth Module JWT Migration"
• "Fix Payment Webhook Race Condition"
• "Add Unit Tests for User Service"
• "Refactor Database Connection Pooling"
• "Debug CORS Issues in API Gateway"

These names make it easy to find specific sessions later, especially when you have dozens of topics in your group. You can always rename a topic manually if the auto-generated name does not capture the essence of the session.

Mobile Coding Tips and Best Practices

Using AI coding agents from your phone is a different experience than using them from a desktop terminal. Here are tips to make the most of it:

Be Specific in Your Instructions

On a desktop, you might iterate rapidly with the agent -- sending short, incremental instructions. On mobile, it is better to be more specific upfront because typing corrections is slower. Instead of "fix the bug," try "In the file src/auth/login.js, the validatePassword function on line 45 does not handle null passwords. Add a null check at the beginning of the function and return false if the password is null."

Use Voice for Long Instructions

When you need to explain something complex, use voice messages. You can speak three to four times faster than you can type on a phone keyboard, and the transcription is very accurate for technical content.

Review Diffs Carefully

OpenACP renders file diffs in Telegram with proper formatting, but reviewing code on a small screen requires more attention. Take your time reviewing changes before approving them. If a diff is too large to read comfortably on your phone, it might be better to wait until you are at your desk.

Use Approve Buttons Judiciously

It is tempting to tap "Approve" on every permission request to keep things moving, but resist the urge. Each permission request is an opportunity to verify that the agent is doing what you expect. Read the description of the action before approving.

Pin Important Topics

If you have long-running sessions that you check on regularly, pin them in your Telegram group. Pinned topics appear at the top of the list, making them easy to find. This is especially useful for sessions that span multiple days or weeks.

Advanced Telegram Features

Beyond the core features, OpenACP's Telegram integration has several advanced capabilities worth exploring:

Session Transfer with /handoff

The /handoff command allows you to transfer a session from Telegram to another platform (or vice versa). This is useful when you start a session on your phone via Telegram but want to continue it on your desktop via Slack or Discord. The session context -- including conversation history and file state -- transfers seamlessly.

Usage Tracking

OpenACP tracks token usage and costs per session. You can check your usage by sending a command in any session. This helps you stay within budget and understand which sessions are consuming the most resources. You can also set budget limits in your configuration to prevent runaway costs.

File Viewer

When an agent reads or modifies files, OpenACP can render them using a Monaco-based file viewer. In Telegram, this appears as a web link that opens a syntax-highlighted, line-numbered view of the file. This is much more readable than raw code in a Telegram message, especially for large files.

Multiple Bots for Multiple Projects

You can create multiple Telegram bots, each connected to a different OpenACP instance and a different workspace. For example, you might have one bot for your main project and another for a side project. Each bot operates independently with its own agent configuration. This keeps your sessions organized by project.

Group Collaboration

Since Telegram groups support multiple members, you can add your team members to the OpenACP group. Everyone can see what the AI agent is doing, and anyone with permission can interact with it. This is powerful for pair programming, code reviews, and knowledge sharing. One developer can start a session, and another can jump in to help guide the agent or review its output.

Notification Management

Telegram offers granular notification controls. You can mute specific topics, mute the entire group, or set custom notification sounds. For long-running sessions where the agent is working autonomously, you might want to mute the topic and check in periodically. For interactive sessions, keep notifications on so you can respond to permission requests promptly.

Security Considerations

When using OpenACP with Telegram, keep these security considerations in mind:

• Bot token security -- never share your bot token publicly. Anyone with the token can control your bot. Store it in your OpenACP config file, which is on your local machine.
• Group privacy -- make your Telegram group private (invite-only) to prevent unauthorized users from joining and interacting with your AI agent.
• Admin controls -- only group admins should be able to interact with the bot in production environments. You can configure this in both Telegram's group settings and OpenACP's configuration.
• Message visibility -- remember that messages in a group are visible to all members. If you are discussing sensitive code or credentials, use a private group with only trusted members.
• Code stays local -- while messages are transmitted through Telegram's servers, your actual source code stays on your development machine. The agent reads and modifies files locally. Telegram only sees the chat messages, not your codebase.

Telegram's end-to-end encryption is available for private chats but not for group chats or bot messages. If you need end-to-end encryption for your coding sessions, consider using OpenACP with a self-hosted messaging solution or restricting sensitive operations to your desktop terminal.

Wrapping Up

OpenACP with Telegram transforms your phone into a remote control for AI coding agents. The combination of forum topics for session organization, real-time streaming for immediate feedback, voice messages for natural input, and permission buttons for secure control creates an experience that is genuinely useful for real-world development work.

Whether you are debugging a production issue from the bus, reviewing code changes from the couch, or speaking instructions to your AI agent while walking the dog, OpenACP and Telegram make it possible. The setup takes minutes, the tools are free, and the experience is polished. There is no reason not to try it.

If you have not already set up OpenACP, head to our getting started guide to install it in under five minutes. And if you want to explore the full range of AI agents available, check out our ACP Registry guide for detailed coverage of all 28+ supported agents.

npm install -g @openacp/cli && openacp