Skip to navigation
Products & Surfaces

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.

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.

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.

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, 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.

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.
  • 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: