docs/usage/channels/telegram.mdx
By connecting a Telegram channel to your LobeHub agent, users can interact with the AI assistant through Telegram private chats and group conversations.
Open Telegram and search for @BotFather — the official Telegram bot for managing bots. Start a conversation and send the /newbot command.
BotFather will ask you to:
bot (e.g., lobehub_assistant_bot)After creating the bot, BotFather will send you an API token (format: 123456789:ABCdefGhIjKlmNoPQRsTuVwXyZ). Copy and save this token.
Important: Your bot token is a secret credential. Never share it publicly.
</Steps>
In LobeHub, navigate to your agent's settings, then select the Channels tab. Click Telegram from the platform list.
Paste the bot token you received from BotFather into the Bot Token field.
The Bot User ID will be automatically derived from your token — no need to enter it manually.
You can optionally enter a Webhook Secret Token for additional security. This is used to verify that incoming webhook requests originate from Telegram.
Click Save Configuration. LobeHub will automatically register the webhook URL with Telegram — no manual URL copying is required.
Your token will be encrypted and stored securely. </Steps>
Click Test Connection in LobeHub's channel settings to verify the integration. Then open Telegram, find your bot by searching its username, and send a message. The bot should respond through your LobeHub agent.
To use the bot in Telegram groups:
@your_bot_username<Callout type={'warning'}> About Group Privacy Mode: Telegram bots have privacy mode enabled by default, which means they only receive messages that @mention the bot, reply to the bot, or contain /commands. If you change the privacy mode setting after creating the bot, you must remove and re-add the bot to the group for the new setting to take effect in that group. </Callout>
Two independent policies gate inbound traffic. Both default to Open.
A populated Allowed User IDs field acts as a global gate — DMs and group @mentions are restricted to listed Telegram numeric user IDs. Empty means "no user-level filter". Grab a user's numeric ID via @userinfobot, or read the from.id field from the bot's incoming update.
Open only when the list is empty: Allowlist then fails closed (no DMs).@mentions.Controls which Telegram groups / channels the bot will respond in.
See the Channels overview for cross-platform details.
| Field | Required | Description |
|---|---|---|
| Bot Token | Yes | API token from BotFather |
| Bot User ID | Auto | Automatically derived from the bot token |
| Webhook Secret Token | No | Optional secret for verifying webhook requests |
| Allowed User IDs | No | Comma- or whitespace-separated Telegram numeric user IDs. Global gate — applies to DMs and group @mentions |
| DM Policy | No | open (default), allowlist, or disabled — who is allowed to DM the bot |
| Group Policy | No | open (default), allowlist, or disabled — where the bot responds in groups |
| Allowed Channel IDs | No | Comma- or whitespace-separated Telegram chat IDs (group IDs are negative). Used when Group Policy is Allowlist |
Disabled, switch to Open or Allowlist. If it is Allowlist, confirm the sender's Telegram user ID (from @userinfobot) is listed in Allowed User IDs.@username to trigger a response. If the bot doesn't respond in a group, try removing the bot from the group and re-adding it — Telegram's privacy mode changes require re-joining the group to take effect.