Telegram Bridge

The Telegram bridge connects Hefty to Telegram, allowing users to send messages to a Telegram bot and have them relayed into Hefty as conversations. Responses from Hefty are sent back through the same Telegram chat.

Prerequisites

  • A Telegram Bot Token from BotFather. See Creating a Telegram Bot below for step-by-step instructions.
  • The bot must be added to any groups or channels you want to bridge.

Creating a Telegram Bot

This section walks through creating a new Telegram bot and obtaining the bot token you will need for configuration.

  1. Open Telegram and search for the BotFather bot.
  2. Start a conversation with BotFather and send the command /newbot.
  3. Choose a display name for the bot — this is the human-readable name shown in chats.
  4. Choose a username for the bot — it must end in bot (e.g., my_hefty_bridge_bot).
  5. BotFather responds with the bot token. Copy and save the token securely — it will be used in the Configuration section below.

Group Privacy

By default, Telegram bots operate in privacy mode, meaning they only receive messages that directly mention them or are replies to their messages. For the Hefty bridge to relay all group messages, privacy mode must be disabled.

  1. Send /setprivacy to BotFather, select your bot, then choose Disable.
  2. Or send /mybots to BotFather, select your bot, go to Bot Settings → Group Privacy, then choose Turn off.
Privacy Mode and Group Bridging

If privacy mode is left enabled, the bot will not receive most group messages and group bridging will not work correctly. Direct-message bridging is unaffected.

For further reading, see the official Telegram Bot Tutorial.

Configuration

Open User Menu → Chat Bridges, select the Telegram tab, and fill in the following fields:

  • Bot Token — the API token provided by BotFather when you created your bot. This field is masked by default; use the show/hide toggle to verify the value.
Protect Your Bot Token

Your bot token grants full control over the bot. Never share it in logs, screenshots, or unencrypted messages.

Testing the Connection

After entering your bot token, click the Test button to verify the connection. On success, you'll see a confirmation message that includes the bot's username. On failure, an error message will describe what went wrong (e.g., invalid token, network issue).

How It Works

Once the bridge is running, messages sent to your Telegram bot (or to a group the bot is a member of) are relayed into Hefty as bridge conversations. These conversations appear in the Conversations sidebar with a TG source badge.

Hefty processes the incoming message through its normal cognition pipeline and sends the response back to the originating Telegram chat. Each Telegram user is tracked individually, so conversations remain separate.

Message Flow

  1. A user sends a message to your Telegram bot.
  2. The Telegram bridge receives the message via polling or webhook.
  3. The message is relayed into Hefty and processed as a bridge conversation.
  4. Hefty's response is sent back to the Telegram chat.