Agent Guidebook
Connect your Agent
Add to Telegram

Add your agent to Telegram

You can add your agent to Telegram as a bot

Use the TelegramTransport Mixin (opens in a new tab) to connect your agent to a Telegram Bot.

A full working example is here (opens in a new tab). You can copy and paste this agent into your file or use it as a reference.


A Mixin is just a way to add a bundle of functionality to your AgentService. Mixins can include new API endpoints, async processing pipelines, and webhooks.

Adding the TelegramTransport Mixin

  1. Add TelegramTransport to the static USED_MIXIN_CLASSES list in your AgentService

  2. Add a bot_token configuration parameter to your agent:

    class ExampleTelegramAgent(AgentService):
        class ExampleTelegramAgent(Config):
            bot_token: str = Field(description="The secret token for your Telegram bot")
            def config_cls(cls) -> Type[Config]:
                return ExampleTelegramAgent.ExampleTelegramAgent
  3. Register TelegramTransport in your AgentService __init__ with


Getting a Telegram Bot Token

To get a Telegram Bot Token:

  1. Contact the @BotFather (opens in a new tab) on Telegram
  2. Run the /newbot command
  3. Name your bot
  4. Copy the bot token that you are given

Testing your Telegram Connection

Python SDK Version

Version 2.17.18 or later of the Steamship SDK is required for this feature.

To use this version, update your `requirements.txt` file and then run `pip install -r requirements.txt`

You do not need to deploy your agent to test the telegram connection -- you can test with Telegram directly from your local machine. Just follow these steps:

  1. Create a config.json file that contains the configuration of your AgentService. This will now include a required bot_token field that contains your Telegram bot token.
  2. Run ship run local -c config.json to run a local copy of your Agent with the provided configuration.

An ngrok account is required to run ship run local. You can connect your account by running: ngrok config add-authtoken YOUR_NGROK_AUTH_TOKEN

It will automatically connect to Telegram using a public NGROK URL.

Using your Telegram Connection in Production

After deploying, when you create an instance from the web just select Optional Configuration from the instance creation screen.

Then enter the telegram_token.

You can find instructions for how to generate a Telegram bot key from the field in the UI.