Telegram Integration Guide
Learn how to integrate your Agent5ive agents with Telegram messaging platform.
Overview
The Telegram integration allows your Agent5ive agents to communicate with users through Telegram, one of the world's most popular messaging platforms. This integration connects your agent directly to a Telegram bot, allowing it to receive and respond to messages automatically.
Key Benefits
- Reach users on a secure, privacy-focused messaging platform
- Provide 24/7 automated support through Telegram
- Maintain conversation context across multiple messages
- Leverage all your agent's capabilities in Telegram conversations
- Easy setup with minimal technical knowledge required
- Process images, voice messages, and text together for rich interactions
- Use in group chats — mention the bot to get responses in shared conversations
Requirements
- An Agent5ive account (Explorer or Pro)
- A Telegram account
- A publicly deployed Agent5ive agent
- A Telegram bot created through BotFather
- The bot's API token
Integration Process
Setting up the Telegram integration is straightforward and only requires a few steps. Follow this guide to connect your agent to Telegram.
Deploy Your Agent Publicly
Before integrating with Telegram, ensure your agent is deployed and published publicly in your Agent5ive dashboard.
Access Telegram Integration
In your Agent5ive dashboard, navigate to your deployed agent and find the 'Telegram Integration' section.
Create a Telegram Bot
Open Telegram and search for @BotFather. Start a chat and send the command /newbot to create a new bot.
Follow BotFather's Prompts
Follow the prompts to name your bot and create a username. BotFather will provide you with an API token.
Copy the API Token
Copy the API token provided by BotFather. It looks something like '123456789:ABCDefGhIJKlmNoPQRsTUVwxyZ'.
Paste and Save
Paste the token in the Telegram Bot API Token field in Agent5ive and click 'Save & Enable'.
Test the Integration
Open your Telegram bot and send a message. Your agent should respond through the bot.
Using in a Group ChatNEW
Your agent's Telegram bot can be added to group chats, allowing it to serve multiple users in a shared conversation. Follow these steps to set it up:
1. Add the bot as a member — open your Telegram group, tap the group name → Add Members, and search for your bot by its username.
2. Promote the bot to Admin — tap the bot's name in the member list → Promote to admin, then save. This allows the bot to read all messages in the group.
3. Mention the bot to get a response — type @YourBotUsername in any message and the agent will reply to your request.
Telegram for Triggers & Scheduled Tasks
Once your agent has a Telegram bot connected, you can use Telegram as an output destination for both event-driven triggers and scheduled tasks.
TriggersPro+ Plans
Send trigger output directly to a Telegram chat. Select "Send to Telegram" or "Both (Database + Telegram)" as the output destination when configuring a trigger. See the Trigger Management guide for details.
Scheduled TasksAll Tiers
Receive scheduled task results in your Telegram chat. Available for all tiers when a Telegram bot is connected. See the Scheduled Tasks guide for details.
Verification Code Setup
To link your Telegram chat as an output destination, you need to complete a one-time verification:
- When configuring a trigger or scheduled task, select Telegram as the output destination
- Click "Generate Verification Code" to get a unique code
- Open your Telegram bot and send the code as a message to the bot
- Once the code is verified, the connection is established
- Click "Create Trigger" or confirm the scheduled task to finalize
This verification ensures the output goes to the correct Telegram chat and prevents unauthorized access.
Customizing Your Telegram Bot
After connecting your agent to Telegram, you may want to customize your bot's appearance and behavior. You can do this through BotFather:
- /setname - Change your bot's name
- /setdescription - Set a description for your bot
- /setabouttext - Set the "About" section of your bot
- /setuserpic - Set a profile picture for your bot
- /setcommands - Set commands for your bot (these appear in the menu)
These customizations help make your bot more professional and user-friendly. Consider adding a profile picture that represents your brand and a clear description of what your bot does.
Best Practices
Optimizing Telegram Interactions
- Keep responses concise and mobile-friendly
- Use Telegram's formatting options (bold, italic, etc.) for better readability
- Consider the limitations of the Telegram interface when designing interactions
- Test your bot thoroughly on both mobile and desktop Telegram clients
- Monitor conversation quality regularly to identify improvement opportunities
Multimodal Interactions
- Enable vision on your agent to process images sent via Telegram
- Configure your system prompt to handle visual content appropriately
- Users will be notified if they send images to non-vision agents
- Images are fetched, converted to data URLs, and processed by your agent
- Combine image analysis with text for richer interactions
- Voice messages are automatically transcribed - all agents can process them
- Agents respond to voice messages with text only, not audio
- Design your agent prompts to handle conversational voice input gracefully
User Experience Tips
- Set up a welcome message that explains what your bot can do
- Provide clear instructions on how to interact with your bot
- Use commands to make common actions easier (e.g., /help, /start)
- Ensure your bot responds promptly to maintain engagement
- Include a way for users to contact a human if needed
Troubleshooting
Common Issues and Solutions
Bot Not Responding
- Verify that your API token is entered correctly
- Ensure your agent is publicly deployed
- Check that your bot hasn't been blocked by the user
- Confirm that your Agent5ive subscription is active
Delayed Responses
- This could be due to high traffic on either Agent5ive or Telegram's servers
- Complex queries may take longer to process
- Check your internet connection
Formatting Issues
- Telegram has specific formatting rules that may affect how messages appear
- Test different message formats to see what works best
- Consider using Telegram's native formatting options
Images Not Being Processed
- Ensure your agent has vision capabilities enabled in Edit Details
- Verify your agent uses a vision-capable model (e.g., Gemini Flash)
- Redeploy your agent after enabling vision
- If vision is not enabled, users will receive a notification that images are not supported
Bot Not Responding in a Group Chat
- Ensure the bot has been promoted to Admin in the group
- Make sure you are mentioning the bot using its exact username (e.g.
@YourBotUsername) - Verify the bot is still a member of the group and has not been removed
- Check that the agent is publicly deployed and the Telegram integration is active
Voice Messages Not Processing
- Ensure your agent is properly deployed and connected to Telegram
- Voice messages are transcribed server-side before being sent to your agent
- If transcription fails, check that the audio file was sent correctly
- Note: Agents always respond to voice messages with text, not audio