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

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

2. Configure in Sophon Dashboard

Go to Channels and click Add Channel
Select Telegram
Paste the bot token
Click Test Connection — you should see a success message
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

Field	Type	Required	Description
`botToken`	secret	Yes	Bot token from BotFather (format: `123456:ABC-DEF...`)

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:

Type	Inbound	Outbound
Text	Yes	Yes
Images (PNG, JPG)	Yes	Yes
Audio / Voice	Yes	Yes
Video	Yes	Yes
Documents (PDF, etc.)	Yes	Yes
Stickers	Yes (converted to image)	No

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.

On this page