> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Setting up a Telegram surface

Connect a Telegram bot to a Product with a Telegram Surface. Runtype sends messages to the bot to a Capability and posts the replies in the Telegram chat.

## Before you begin

Make sure that you have these items:

* A Product.
* The Capability that handles Telegram messages.
* A Telegram account on your phone or desktop.

You don't need a bot yet. Runtype can create one for you, or you can connect a bot that you created with @BotFather.

## Create a Telegram Surface

To create the Surface and choose its Capability, follow these steps:

1. Open the Product that you want to connect to Telegram.
2. Open **Surfaces** and click **Add Surface**.
3. Under **Messaging Channels**, select **Telegram Channel**. The Surface panel opens on the **General** tab.
4. In **Capability**, select the Capability that you want to run.
5. Click **Save Changes**.

A new Surface starts as **Draft**. Runtype sets it to **Active** when you connect a bot.

For more information about Capabilities, see [Adding capabilities to a Product](/user-guide/products-surfaces/adding-capabilities-to-a-product).

## Connect a bot

On the **Inbound** tab, **Telegram Bot Setup** offers two ways to connect a bot. Choose one of the following options.

### Create a bot from Runtype

To create a bot without @BotFather, follow these steps:

1. Click the **Inbound** tab, and then click **Create New Bot**.
2. In **Bot Name**, enter the display name that Telegram shows in chats.
3. Optional: Edit the **Username**. Runtype suggests one from the bot name. The username must end in `_bot`.
4. Optional: Enter a **Description**.
5. Click **Create Bot**.
6. Click **Open in Telegram**. Telegram shows a confirmation with a temporary name and your username.
7. In Telegram, keep the temporary name and confirm. Runtype replaces the temporary name with your bot name.
8. Return to Runtype and wait. When the bot is ready, the panel shows **Telegram Bot Connected** and the bot's username.

If Telegram assigns a different username, for example because yours is taken, Runtype shows **The bot username changed**. Click **Yes, this is my bot** to finish, or **No, this isn't mine** to start again.

If automatic creation isn't available, **Create New Bot** opens the manual setup instead.

### Connect an existing bot

To connect a bot that you created with @BotFather, follow these steps:

1. Click the **Inbound** tab, and then click **Connect Existing Bot**.
2. Optional: To create a bot, click **Open @BotFather** and send the `/newbot` command.
3. Click **Continue**.
4. In **Bot Token**, paste the token that @BotFather gave you. A token has the form `1234567890:ABCdef...`.
5. Click **Continue**. Runtype checks the token and shows **Connected as** and the bot's username. If the check doesn't start, click **Validate Token**.
6. Click **Finish Setup**. The panel shows **Telegram Bot Connected**.

When you finish setup, Runtype registers the Surface's webhook with Telegram, sets a webhook secret, activates the Surface, and adds the `/start`, `/help`, and `/reset` commands to the bot's menu. You don't need to configure anything in Telegram.

To connect a different bot later, click **Reconfigure** on the **Inbound** tab.

## Choose how the bot responds in groups

In a private chat, the bot answers every message. In a group, the **Channel response mode** setting on the **Inbound** tab decides which messages the bot answers:

* **Mention only**: answers messages that mention the bot, such as `@acme_support_bot`, and replies to the bot's own messages. New Surfaces use this mode.
* **Every message**: answers every message in the group.

Telegram delivers every group message to a bot only when the bot's privacy mode is off or the bot is a group administrator. To use **Every message**, send `/setprivacy` to @BotFather and turn privacy mode off, or make the bot an administrator.

A Telegram Surface also accepts the `judge` mode through the API. For details, see [Judge mode](/user-guide/products-surfaces/setting-up-a-slack-surface#judge-mode).

## How conversations work

Each private chat, group, or forum topic is one conversation. Everyone in a group shares that group's conversation. Send `/reset` to close the conversation. The bot replies `Conversation reset. Send a new message to start fresh.`, and the next message starts a new conversation.

While the Capability runs, the bot posts the **Loading Indicator** character and then updates the message as the reply arrives. To change the character, set **Loading Indicator** on the **Outbound** tab. The default is `█`.

The bot processes text messages. For a photo or file with a caption, the caption is the message text. For a sticker, a video, or media without a caption, the bot asks the person to send text instead.

When the Surface has one enabled Capability, or one Surface item marked as the entry point, that Capability answers every message. Otherwise, a billed routing judgment chooses a Capability, and the conversation keeps it. For details, see [Surfaces with several Capabilities](/user-guide/products-surfaces/setting-up-a-slack-surface#surfaces-with-several-capabilities).

The **Outbound** tab also has a **Welcome Message** field. Runtype saves it but doesn't send it on a Telegram Surface. The `/start` and `/help` commands reach the Capability as ordinary text. To greet new users, handle `/start` in the Capability's instructions.

## Approve tool calls in Telegram

When an attached Agent uses [**Tool approval**](/user-guide/agents/creating-and-configuring-agents), the bot posts the request with **Approve** and **Deny** buttons. Only the person who started the conversation can decide. Taps from other group members don't resolve the approval.

For a Runtype Agent, button approval requires an **Agent loop** with **Max turns** set to 2 or higher. A Managed external Agent already supports multi-turn tool approval. For the full rules, see [Approvals on messaging surfaces](/user-guide/products-surfaces/approvals-on-messaging-surfaces).

## Test the connection

To verify the connection, follow these steps:

1. In Telegram, search for the bot's username, which the **Inbound** tab shows, and open a private chat with the bot.
2. Send a message, such as `Hello`.
3. Confirm that the bot shows the loading indicator and then the reply.
4. In the Product, open **Activity** and confirm that the conversation appears.

Your Telegram Surface is ready when the reply arrives. Test in a private chat first, and then add the bot to a group.

## Troubleshoot the connection

If the bot doesn't reply, check these settings:

* **Status**: set the Surface **Status** to **Active** on the **General** tab. Draft, Paused, and Archived Surfaces don't accept messages.
* **Group messages**: in **Mention only** mode, mention the bot or reply to one of its messages. In **Every message** mode, turn off the bot's privacy mode or make the bot an administrator.
* **Rejecting events**: if the channel shows **Rejecting events** in the product editor, the webhook secret that Telegram sends doesn't match the Surface. Click **Reconfigure** on the **Inbound** tab and connect the bot again. For more information, see [Inbound webhook rejected](/user-guide/troubleshooting-faq/common-errors-and-solutions#inbound-webhook-rejected).
* **Slow bot creation**: if **Create New Bot** waits for more than 90 seconds, make sure that you confirmed the bot in Telegram. To stop waiting, click **Connect an existing bot instead**. The request times out after 10 minutes.

If the bot sends an error reply instead of an answer, check these settings:

* **Capability**: select a Capability on the **General** tab and click **Save Changes**.
* **Debug Mode**: while you test, turn on **Debug Mode** on the **Outbound** tab. The bot then sends intermediate step outputs, tool calls, and execution details to the chat. Turn it off before other people use the bot.

## Next steps

Continue with these guides:

* [Approvals on messaging surfaces](/user-guide/products-surfaces/approvals-on-messaging-surfaces): compare how each messaging Surface collects tool approvals.
* [Setting up a Slack surface](/user-guide/products-surfaces/setting-up-a-slack-surface): connect the same Product to a Slack workspace.
* [What are Surfaces?](/user-guide/products-surfaces/what-are-surfaces): review the available Surface types.
* [Surface orchestration modes](/user-guide/products-surfaces/surface-orchestration-modes): compare how each Surface type picks a Capability.