How to connect Telegram to an AI Agent

Connect your Flametree AI agent to Telegram to enable automated conversations through one of the world's most popular messaging platforms. This integration allows your agent to respond to users directly in Telegram chats.

Prerequisites

• Access to Telegram (mobile app or web version)
• A Flametree account with agent creation permissions
• Admin access to the Flametree integration settings

Creating and Configuring Telegram Bot

Step 1: Create a Telegram Bot

1. Find BotFather

   • Open Telegram and search for @BotFather (official bot)
   • Send the /start command to begin

2. Create New Bot

   • Send /newbot command
   • Follow the setup wizard:
     • Bot Name: Choose a display name (e.g., "My Company Support")
     • Username: Must end with bot (e.g., mycompany_support_bot)

3. Save Your Token

   • BotFather will provide an access token in format: 123456789:AAH...XYZ
   • Keep this token secure - you'll need it for Flametree integration

⚠️ Warning: Store the bot token safely. Anyone with this token can control your bot.

Step 2: Configure Integration in Flametree

1. Navigate to Integrations
   • Go to Channels section in Flametree
   • Find Telegram card and click Add +

💡 Note: Telegram integration from Integrations section is outdated. Use Channels instead.

2. Fill Configuration

Field	Description	Required	Default
Name	Custom name for this integration	✅ Yes	-
Description	Optional description for internal reference	✅ Yes	-
Telegram Bot Token	Token received from @BotFather	✅ Yes	-
Enable telegram streaming	Real-time AI answer generation	❌ No	True

3. Save Integration
   • Click Save to create the integration

Step 3: Connect to AI Agent

1. Open Agent Configuration

   • Navigate to your target AI agent's settings
   • Go to Channels section

2. Assign Channel

   • Select your Telegram integration from the list
   • Save the agent configuration

3. Restart Agent

   • Restart the agent for changes to take effect
   • This step is mandatory for the integration to work

❗️ Important: Always restart both the agent and channel after making changes.

Configuration Options

Environment Variables

Customize behavior through Set Environment Variables:

Variable	Default	Description	Scope
SHOW_VOICE_TRANSCRIPTION	true	Show transcription text for voice messages	Integrations & Channels
TELEGRAM_SHOW_KEYBOARD_REPLY	true	Display control buttons (clear, thoughts, stop)	Integrations only

To configure:

1. Go to your agent's Set Environment Variables
2. Add the variable name and desired value
3. Save and restart the agent

Testing Your Integration

Quick Test Steps

1. Find Your Bot

   • Search for your bot username in Telegram
   • Start a conversation with /start

2. Send Test Message

   • Type any message to your bot
   • Verify the AI agent responds appropriately

3. Test Voice Messages (if enabled)

   • Send a voice message
   • Check if transcription appears (if SHOW_VOICE_TRANSCRIPTION is true)

Common Issues & Solutions

Bot not responding to messages

Possible causes:

• Agent not restarted after integration setup
• Invalid bot token
• Bot token belongs to a different bot

Solutions:

1. Verify bot token: Check with @BotFather using /mybots
2. Restart agent: Go to agent settings and restart
3. Check logs: Review integration logs for error messages
4. Re-create bot: If token is compromised, create a new bot

Voice messages not working

Possible causes:

• Voice transcription disabled
• Missing Speech-to-Text integration
• Unsupported audio format

Solutions:

1. Enable transcription: Set SHOW_VOICE_TRANSCRIPTION to true
2. Configure STT: Set up Speech-to-Text integration if needed
3. Check format: Ensure voice files are in supported formats
4. Test with different devices: Some devices may have audio issues

Streaming responses not working

Possible causes:

• Streaming disabled in integration settings
• Network connectivity issues
• Agent configuration problems

Solutions:

1. Enable streaming: Set Enable telegram streaming to true
2. Check connection: Verify network connectivity
3. Restart services: Restart both agent and integration

FAQ

Can I use the same bot token for multiple agents?

No, if you use Integration Yes, if you use Channel.

How do I customize my bot's appearance?

Use @BotFather commands:

• /setuserpic - Change profile picture
• /setdescription - Update bot description
• /setabouttext - Set "About" section text
• /setcommands - Define available commands

Why does my bot show "offline" status?

This is normal behavior. Telegram bots don't show online/offline status like regular users. All bots appear without status indicators.

Can users see the bot is automated?

Yes, Telegram clearly marks bots with a "BOT" label next to their name. This is a platform requirement and cannot be removed.

What message types are supported?

Flametree Telegram integration supports:

• ✅ Text messages
• ✅ Voice messages (with transcription)
• ✅ Images
• ✅ Group management features
• ❌ Documents and files
• ❌ Video calls

How to enable Telegram streaming?

To enable real-time AI response streaming:

1. During Integration Setup: Check the "Enable telegram streaming" option when creating your Telegram channel
2. For Existing Integration: Edit your Telegram channel settings and set "Enable telegram streaming" to True
3. Restart Required: Restart the channel after making changes

When enabled, users will see AI responses being typed in real-time rather than waiting for the complete response.

Security Considerations

Bot Token Security

• Never share your bot token publicly
• Rotate tokens if compromised using @BotFather
• Use environment variables in production deployments
• Monitor bot usage for suspicious activity

Privacy Settings

• Configure bot privacy settings via @BotFather using /setprivacy
• Consider group chat permissions if bot will be used in groups
• Review message retention policies in your Flametree account

Related Resources

• Telegram Bot API Documentation
• Creating Knowledge Bases
• Agent Configuration Guide