Skip to Content
IntegrationsTelegram Integration

Telegram Integration

Connect your Hatcher agent to Telegram so users can chat with it directly in a Telegram conversation. This is the easiest integration to set up — it takes about 2 minutes.

Prerequisites

  • A Telegram account (download from telegram.org )
  • A Hatcher agent already created (Getting Started)
  • Telegram integration is free on all Hatcher plans

Setup

Open BotFather on Telegram

Open Telegram and search for @BotFather. Make sure you select the one with the blue verified checkmark — this is the official Telegram bot for creating and managing bots.

You can also open it directly: https://t.me/BotFather 

Create a new bot

Send the /newbot command to BotFather. It will ask you two things:

  1. Display name — The name shown in chats (e.g., “My Crypto Agent”). This can be changed later.
  2. Username — A unique handle that must end in bot (e.g., MyCryptoAgentBot or mycrypto_bot). This cannot be changed later, so choose carefully.

Copy the bot token

After creating the bot, BotFather will reply with a message containing your HTTP API token. It looks like this:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Copy this token. Keep it secret — anyone with this token can control your bot.

Never share your bot token publicly, commit it to Git, or post it in chat. If your token is compromised, go back to BotFather and use /revoke to generate a new one.

Configure in Hatcher

  1. Go to your Hatcher Dashboard
  2. Navigate to My Agents and select your agent
  3. Open the Integrations tab
  4. Find Telegram and click Configure
  5. Paste your Bot Token into the token field
  6. Click Save

Restart your agent

After saving the token, click Restart on your agent to apply the new configuration. The agent will reconnect with Telegram within a few seconds.

Test it

Open Telegram, find your bot by its username (e.g., @MyCryptoAgentBot), and send it a message. Your agent should respond.

Optional: Customize Your Bot

Back in BotFather, you can send these commands to customize your bot’s appearance:

CommandDescription
/setdescriptionShort description shown when users open the bot for the first time
/setabouttextText shown in the bot’s profile
/setuserpicUpload a profile photo for your bot
/setcommandsDefine slash commands (e.g., /help, /status)

Group Chats

By default, Telegram bots in group chats only receive messages that start with / commands or explicitly mention the bot. To let your agent see all messages in a group:

  1. Open BotFather
  2. Send /setprivacy
  3. Select your bot
  4. Choose Disable

This lets your agent participate naturally in group conversations.

Privacy mode changes only apply to groups the bot joins after the setting is changed. Remove and re-add the bot to existing groups.

Troubleshooting

Bot not responding

  • Check the token format. It should look like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ (a number, colon, then an alphanumeric string). If you accidentally copied extra whitespace or characters, re-paste it.
  • Make sure the agent is running. Go to your Hatcher dashboard and verify the agent status is Active (green). If it’s paused or errored, check the logs.
  • Restart the agent after saving the token. Configuration changes don’t take effect until the container restarts.

Bot responds to DMs but not in groups

  • Send /setprivacy to BotFather and set it to Disable for your bot (see Group Chats section above).
  • Remove the bot from the group and re-add it after changing the privacy setting.

”Unauthorized” error in logs

Your bot token is invalid or has been revoked. Go to BotFather, use /revoke on your bot, copy the new token, and update it in Hatcher.

”Conflict: terminated by other getUpdates request”

Another instance of your bot is running somewhere else (perhaps a local test). Only one process can poll for updates at a time. Stop the other instance, then restart your Hatcher agent.

Rate limiting

Telegram limits bots to approximately 30 messages per second globally, and 1 message per second per chat. If your agent is very active, you may see occasional delays. This is a Telegram-side limit and cannot be changed.

Last updated on
Slack IntegrationTwitter / X Integration