Telegram

Sophon connects to Telegram using the official Bot API. You'll create a bot through BotFather and paste the token into Sophon.

Prerequisites

• A Telegram account
• The Telegram app (mobile or desktop)

Step-by-Step Setup

1. Create a Bot with BotFather

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Choose a display name (e.g., "Sophon Assistant")
4. Choose a username ending in bot (e.g., sophon_assistant_bot)
5. BotFather replies with your bot token — copy it

2. Configure in Sophon Dashboard

1. Go to Channels and click Add Channel
2. Select Telegram
3. Paste the bot token
4. Click Test Connection — you should see a success message
5. Click Activate

3. Test It

Open a chat with your bot on Telegram and send a message. Sophon should respond.

Optional: Set Bot Commands

Send these to BotFather to add a command menu:

/setcommands

Then paste:

start - Start a conversation
help - Show available commands

Configuration Reference

channels.json Example

{
  "id": "telegram-bot",
  "type": "telegram",
  "name": "Sophon Telegram Bot",
  "enabled": true,
  "config": {
    "botToken": "<encrypted>"
  },
  "routing": {
    "agentId": "default",
    "dmBehavior": "main-session",
    "groupBehavior": "mention-only"
  },
  "status": "connected"
}

Media Support

Telegram supports rich media in both directions:

Troubleshooting

• "401 Unauthorized" — The bot token is invalid or has been revoked. Generate a new one with /token in BotFather.
• Bot doesn't respond in groups — By default, groupBehavior is set to mention-only. Mention the bot with @username or change the setting to all-messages. You may also need to disable Privacy Mode via BotFather (/setprivacy > Disable).
• Duplicate messages — Ensure only one Sophon instance is running with the same bot token. Telegram does not allow multiple clients on the same bot token.
• Media not received — Check that the ~/.sophon/documents/uploads/ directory is writable and has sufficient disk space.

Group behavior

In groups, Sophon responds according to the channel's group policy (mention-only by default on Pro/Enterprise; Personal-tier instances respond to all group messages — see Group Chats). Telegram supports all four mention triggers: explicit @mentions of the bot, replies to the bot, quotes of the bot's messages, and forum-topic participation.

When a user replies to an earlier message, Telegram delivers the quoted message in the update itself, so Sophon captures the quoted author and text as agent context with no extra API call.

Each Telegram forum topic gets its own isolated session — a child of the group's session with separate history and context, expired automatically after a period of inactivity.

See Group Chats for policies and allowlists, and Threads & Sessions for thread session lifecycle and configuration.