Telegram Channel Setup

Connect your AI agent to Telegram, enabling users to chat with your agent through Telegram's messaging platform either individually or in groups.

Overview

A Telegram channel allows your agent to:

• Receive messages from users in direct messages or group chats

• Send text, images, videos, and other media

• Support rich media content in conversations

• Work seamlessly across Telegram's web, mobile, and desktop apps

Prerequisites

Before you begin, you'll need:

1. A Telegram account - You'll need a Telegram account to create a bot

2. A published agent in your Stage5 project that you want to connect to Telegram

Step 1: Create a Telegram Bot

1. Open Telegram and search for @BotFather (Telegram's official bot for creating bots)

2. Start a conversation with BotFather

3. Send the command /newbot

4. BotFather will ask for a name for your bot - choose a descriptive name (e.g., "Customer Support Assistant")

5. Next, choose a username for your bot. It must end with bot (e.g., my_customer_support_bot)

6. If the username is available, BotFather will confirm and provide you with a bot token

7. Save this token - you'll need it in Step 3 (it looks like: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz . See the image below. You need the copy all of the line marked in the red arrow)

Step 2: Configure Bot Settings (Optional)

You can customize your bot with BotFather:

• Set bot description: Use /setdescription to tell users what your bot does

• Set bot picture: Use /setuserpic to add a profile picture

• Set about text: Use /setabouttext to add a short "About" message

Step 3: Save the token as a secret in Stage5

Required Secrets

You'll need to store the bot token as a secret in your project's Secret Vault:

• Bot Token Secret Key - The expected value is the name of the secret storing your Telegram bot token (from Step 1). The assistant will use a placeholder name like telegram-bot-token, which you can change if needed.

Inside a project, click on the cog sign in order to access the project settings:

Once in the project settings, click on the Secrets menu item and add a new secret by following these instructions:

1. Click the Add Secret button in the top-right corner

2. Fill in the secret information:

   • Secret Key (Required): A unique identifier for your secret (e.g., telegram-bot-token)

   • Secret Value (Required): The actual secret value (the token)

   • Description (Optional): A note about what this secret is used for and extra relevant information for your team members (for example, how to get this value in case that's needed).

3. Click Create Secret to save

Step 4: Configure the Channel in Stage5

In your Stage5 project, in order to create or edit a channel manifest file, just instruct the assistant. For example: "Connect the Customer Support Agent to a Telegram channel. Make sure to have placeholders for all of the Secrets that are needed and I'll add them later." Behind the scenes the Stage5 Assistant will create it all, leaving you just to set the secrets.

What Gets Created

When you instruct the assistant, it will create a channel manifest file similar to this:

{
  "kind": "channel",
  "version": "1",
  "channel": {
    "type": "telegram",
    "name": "Customer Support Telegram Bot",
    "description": "AI assistant for customer support via Telegram",
    "agentManifestPath": "agents/support-agent.json",
    "telegramOptions": {
      "botTokenSecretKey": "telegram-bot-token"
    },
    "selfRegistrationForExistingUsersEnabled": true,
    "selfRegistrationForNewUsersEnabled": true
  }
}

Required Secrets

You'll need to store the bot token as a secret in your project's Secret Vault:

• Bot Token Secret Key - The name of the secret storing your Telegram bot token (from Step 1). The assistant will use a placeholder name like telegram-bot-token, which you can change if needed.

Configure the required secrets. For more information see the "Storing Secrets" section.

Step 4: Publish Your Channel

1. Publish your channel to the desired environment (Production, Staging, etc.)

2. Stage5 will automatically configure the webhook with Telegram

3. Your bot is now ready to receive messages!

Step 5: Test Your Channel

1. Open Telegram and search for your bot using its username (the one ending in bot)

2. Start a conversation with your bot by clicking "Start" or sending /start

3. Send a test message

4. Your agent should respond within a few seconds

5. If you don't receive a response, check:

   • Your bot token is correctly stored in the Secret Vault (see "Storing Secrets" section)

   • The channel was successfully published

Configuration Options Reference

Channel Name

• Type: String

• Required: Yes

• Description: A descriptive name for your Telegram channel (e.g., "Customer Support Bot")

Channel Description

• Type: String

• Required: Yes

• Description: Brief explanation of what this channel is for

Agent Manifest Path

• Type: String

• Required: Yes

• Description: Path to your agent manifest file (e.g., "agents/support-agent.json")

Bot Token Secret Key

• Type: String (secret key name)

• Required: Yes

• Description: The name of the secret in your Secret Vault that stores your Telegram bot token (obtained from BotFather)

Self-Registration Options

See the main Channels documentation for details on:

• selfRegistrationForExistingUsersEnabled

• selfRegistrationForNewUsersEnabled

• selfRegistrationForExistingUsersDisabledMessage

• selfRegistrationForNewUsersDisabledMessage

• userDisabledMessage

• userDeletedMessage

Troubleshooting

Bot Not Responding

• Check bot token: Verify your bot token is correctly stored in the Secret Vault and matches the token from BotFather (see "Storing Secrets" section)

• Check agent: Verify your agent is correctly configured and published

• Test with BotFather: Use /getme command with BotFather to verify your bot token is still valid

Can't Find Bot in Telegram

• Check username: Make sure you're searching for the correct username (ending in bot)

• Bot may be disabled: If you disabled your bot with BotFather, re-enable it with /unfreeze

• Typo in username: Double-check for typos in the username

Bot Not Receiving Messages

• Webhook configuration: Stage5 automatically configures the webhook when you publish. If messages aren't coming through, try republishing the channel

• Check bot status: Use BotFather's /getme command to ensure your bot is active

• Group permissions: In group chats, verify the bot has permission to read messages

Invalid Token Error

• Token format: Ensure your token looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz (numbers, colon, letters/numbers)

• Token expiry: Bot tokens don't expire, but double-check you copied the entire token correctly

• Regenerate if needed: You can always generate a new token with BotFather using /token if needed

Best Practices

1. Clear bot description: Set a helpful description so users know what your bot does

2. Welcome message: Consider setting an about text that welcomes users and explains what the bot can help with

3. Handle /start command: Your agent should handle the /start command, which users typically send when first chatting with a bot

4. Test in private first: Test your bot in direct messages before adding it to group chats

5. Monitor usage: Keep an eye on how users interact with your bot to improve responses

Security Considerations

• Never share your bot token: Keep your bot token secure and only store it in your Secret Vault

• Token regeneration: If you suspect your token is compromised, you can regenerate it with BotFather using /revoke and /token

• Group chat moderation: In public groups, consider implementing moderation to prevent abuse

• Rate limiting: Telegram has rate limits - Stage5 handles these automatically, but be aware of them for high-traffic bots

Advanced Features

Webhooks vs Long Polling

Stage5 uses Telegram's webhook API for real-time message delivery. This provides:

• Faster message delivery

• More reliable connections

• Automatic webhook management

The webhook is automatically configured when you publish your channel, so you don't need to worry about this technical detail.

Getting Help

If you encounter issues:

1. Check the Troubleshooting section above

2. Verify your configuration matches the examples

3. Test with BotFather commands to ensure your bot token works

4. Ensure your agent is correctly configured and published

5. Check Stage5 logs for any error messages. If needed you can also reach out to us in our Slack Community.