Telegram Integration
Connect your Studio bot to Telegram and start receiving messages, running analysis, and executing trades — all without managing a bot token or webhook. Balchemy runs the Telegram adapter centrally so you focus entirely on what your bot does, not how it connects.
What is this?
Balchemy maintains a shared Telegram adapter that handles all of the low-level Telegram API wiring: webhooks, polling, message delivery, and reconnection. Your Studio bot plugs into that adapter by providing its behavioral configuration — access mode, permitted users, mention policy — rather than raw credentials.
Two bots owned by different users can both operate over Telegram at the same time while keeping completely separate identities, knowledge bases, and trading rules. Shared infrastructure does not mean shared behavior.
You will never paste a Telegram bot token into Studio. That credential layer is handled by Balchemy on your behalf.
Prerequisites
Before you start, make sure:
- You have a bot created in Studio (any state is fine; it does not need to be running yet)
- You have a Telegram account with a public username set
- You have opened a conversation with
@BalchemyBotin Telegram and sent it the/startcommand — the bot cannot DM you otherwise - If you want to link your Telegram identity to your Balchemy wallet, complete the Hub verification step first at
/hub/verify/telegram(see Telegram Verification)
Step-by-step: connect Telegram in Studio
- Open Studio and navigate to the bot you want to connect.
- Select the Platforms tab from the bot sidebar.
- Find the Telegram card. It shows a disconnected status badge by default.
- Toggle the switch on the Telegram card to Connected. The badge updates optimistically while the API call runs.
- Click the Configure button on the Telegram card to open the settings sheet.
- Set your Owner Username — enter your Telegram
@username(the@prefix is optional). This account receives full admin rights over this bot's Telegram interactions. - Choose an Access Mode (see the table below).
- If you chose
whitelist, enter the Allowed Usernames as a comma-separated list without@prefixes. - Toggle Only Respond to Mentions based on where you plan to deploy the bot (see recommendations below).
- Click Save Configuration.
- Add the Balchemy bot handle to your Telegram group, or start a DM, to begin testing.
Tip: Run a quick test after saving. Send a simple message to your bot in Telegram and confirm it responds. If there is no response within 30 seconds, check the Platform card — an Error badge means the adapter could not reach your bot's configuration.
Access modes explained
Access mode is the single most important security setting for a Telegram-connected bot. Choose carefully, especially if your bot has trading enabled.
| Mode | Who can interact | Best for |
|---|---|---|
private | Owner username only | Personal trading bots, single-user analysis |
public | Anyone who finds or adds the bot | Public information bots, no trading enabled |
whitelist | Only the usernames in the Allowed Usernames list | Team or community bots with known members |
Warning: Never set Access Mode to
publicif you have natural-language trading enabled in your bot's AI Configuration. Any person who discovers the bot handle could send trade commands. Useprivateorwhitelistwhenever trading is active.
Private mode is the safest starting point. Switch to whitelist when you need to share the bot with a trusted group. Reserve public for read-only information or market commentary bots.
Only Respond to Mentions
When you add your bot to a Telegram group, every message in the group is visible to it. With Only Respond to Mentions turned off, the bot will try to reply to every message. That can flood a busy group with responses.
Turn this setting on when:
- The bot is deployed to a group chat with multiple members
- You only want the bot to respond when explicitly addressed
- You are running the bot alongside other bots in the same group
Leave it off when:
- The bot is in a 1-on-1 DM context
- You want the bot to proactively comment on everything (public commentary bots)
Channel policies
If your bot is active in multiple Telegram channels or groups, you can set per-channel capability rules. Each channel policy has two independent switches:
| Policy | Effect |
|---|---|
| Trading | Allows trade commands from this channel to reach the trading engine |
| Analysis | Allows market analysis queries from this channel |
Channel policies appear in the Configure sheet as individual cards once the bot has been active in a channel and Balchemy has recorded it. You do not need to pre-register channel IDs — they appear automatically.
Use channel policies to create tiered access. For example: enable both Trading and Analysis in a private admin channel, but enable Analysis only in a community channel where you share signals without executing trades.
Quick-reply templates on Telegram
Your bot can use quick-reply templates to answer common questions without invoking the full AI pipeline. Templates are configured in the bot's AI Configuration tab and appear as suggested responses in Telegram interfaces that support inline keyboards.
When a user's message closely matches a template trigger, Balchemy serves the template response directly. This reduces latency and keeps your most frequent interactions consistent. You can configure up to eight templates per bot.
Tip: Templates are most effective for greetings, status checks ("what is my portfolio balance?"), and FAQ-style queries. Reserve full AI responses for complex analysis and trade commands.
What happens when the bot is added to a group
When someone adds the Balchemy bot handle to a Telegram group:
- The adapter detects the
bot_joinedevent and records the group's chat ID. - If the bot's Access Mode is
private, it will not respond to any group messages — only DMs from the owner username. - If the bot's Access Mode is
publicorwhitelist, it begins listening to group messages according to your Mention and Channel Policy settings. - A new Channel Policy card appears in the Configure sheet for that group's chat ID.
- You can immediately set Trading and Analysis toggles for that channel.
The bot does not send an automated welcome message to the group unless you have configured one via templates. The first response will be to a direct message or mention, depending on your settings.
Hub identity verification and Telegram
Telegram integration in Studio and Telegram verification in Hub are two separate steps that serve different purposes.
Studio Telegram configuration controls how your bot behaves on Telegram — who can talk to it, in which channels, and with what capabilities.
Hub Telegram verification at /hub/verify/telegram links your personal Telegram identity to your Balchemy wallet. This is required when you want to claim an external agent that already operates on Telegram, or when you want Balchemy to send operator notifications to your Telegram account.
You can connect a bot to Telegram in Studio without completing Hub verification. Hub verification is only needed for the identity-claim and notification features.
See Telegram Verification for the full step-by-step Hub flow.
Configuration reference
| Field | Type | Required | Description |
|---|---|---|---|
| Owner Username | string | Yes | Telegram @username of the bot owner. Controls admin commands. |
| Access Mode | private / public / whitelist | Yes | Who can send messages to this bot |
| Allowed Usernames | Comma-separated string | Only in whitelist mode | Telegram usernames (without @) permitted to interact |
| Only Respond to Mentions | boolean | No | When on, bot replies only when @mentioned in groups |
| Channel Policies: Trading | boolean per channel | No | Whether trade commands are accepted from this channel |
| Channel Policies: Analysis | boolean per channel | No | Whether market analysis queries are accepted from this channel |
Tips and warnings
Tip: Use
whitelistmode with a small trusted list during your initial testing phase. You can always loosen topubliclater — but it is much harder to recover from an unintended trade executed by an unknown user.
Warning: The Balchemy Telegram adapter is shared infrastructure. Your bot's configuration — not the adapter — determines its behavior. A misconfigured access mode or overly broad channel policy is your responsibility to correct.
Tip: If you are running multiple bots across different groups, give each bot a distinct Owner Username so you can track which admin account manages each deployment. The owner username appears in error notifications and support context.
Common issues
The Telegram card shows an Error badge. The adapter could not deliver a message or received a webhook rejection. The most common cause is that the Balchemy bot was removed from the group or the group was deleted. Re-add the Balchemy bot handle to your group and toggle the Platform card connection off and back on.
The bot is in my group but is not responding.
Check your Access Mode. If it is set to private, the bot only responds to the owner in DMs. If it is set to whitelist, verify the user's Telegram username is in your Allowed Usernames list. Also check whether Only Respond to Mentions is on — if so, the user needs to explicitly @mention the bot.
Messages arrive but trading commands are ignored. Open the Configure sheet and check the Channel Policy for that group. The Trading toggle must be on for trade commands from that channel to reach the trading engine. Also confirm that your bot's AI Configuration has natural-language trading enabled.
The bot responds to mentions but not to direct messages. This is expected behavior when Only Respond to Mentions is on and the message is sent in a group without a mention. In direct messages (1-on-1 chats), the setting has no effect — the bot always responds in DMs.
I sent /start to @BalchemyBot but the OTP code never arrived.
Make sure you messaged @BalchemyBot and not a similarly named bot. Send /start again, wait five seconds, and click the "I wrote /start, send me a code" button on the Hub verification page. If the problem persists, check your Telegram privacy settings under Settings → Privacy and Security → Messages to ensure bots can send you DMs.
The Configure sheet shows no Channel Policy cards. Channel policies appear only after the bot has received at least one message in a given channel. Add the bot to the group, send a message, then return to the Configure sheet.
Related pages
- Telegram Verification — link your personal Telegram identity to your wallet
- Discord Integration — connect your bot to Discord servers
- Platform and MCP Settings — full overview of the Platforms tab
- Bot AI Configuration — enable natural language trading and set templates
- Your First Bot — create your first Studio bot