dsh-telegram-bot
Telegram client for DeepSeek Harness. It connects a DSH profile to a Telegram bot and keeps the same DSH sessions available in both interfaces.
Demo
First setup: https://youtu.be/QEeVucfBsWk
Installation, bot token, the allowlist, /start, /sessions and a test prompt.
Enable Threaded mode
BotFather: Bot Settings → Threaded mode → Enable
BotFather: Bot Settings → Threaded mode → Enable.
Features
- One Telegram topic per DSH session; Web and Telegram use the same session.
- Telegram mirrors only turns initiated from Telegram; turns started in the Web UI stay in Web.
/sessions lists workspaces and existing sessions, and can create a new session in a selected workspace.- Assistant answers stream into the topic with Telegram Markdown formatting.
- Reasoning and tool calls are shown as temporary messages and removed after the answer. Each tool-call entry is capped at two lines.
- Inline controls for model, reasoning effort, permission mode and context usage.
- Tool approvals with Deny / Allow buttons.
ask_user_question support: options, multi-select, custom answers and plan review.- Documents and photos sent in a session topic are saved as DSH attachments and passed to the agent.
/last, /rename, /fork, /stop, /restart, /status and /menu./fork [name] creates a DSH session fork in a new Telegram topic; without a name it uses the previous title plus the branch number.- The session picker also has 🔀 Continue in Telegram fork; automatic fork topics end with
(N).
- English and Russian bot messages.
- Bot token stays in the DSH credential store.
Requirements
- DSH
0.2.1-rc.2 or newer, Node.js 22+.
- A Telegram bot token from @BotFather.
- Threaded mode enabled in BotFather and Topics enabled in the bot chat.
Install
From this repository:
npx @deepseek-ai/dsh plugin --profile web add .
From npm:
npx @deepseek-ai/dsh plugin --profile web add dsh-telegram-bot@latest
Restart dsh web after installing or updating the plugin. Then open Settings → Telegram.
Configure
| Field | Meaning |
|---|
| Bot token | Token from @BotFather; stored in the credential store |
tokenRef | Credential/env name for the token; default TELEGRAM_BOT_TOKEN |
cwd | Working directory for Telegram-created sessions |
agentPreset | Preset mounted for Telegram sessions; default standard |
| Allowed users | Telegram user ids or @usernames |
| Allowed chats | Telegram chat ids or @channelnames |
| Show model thinking | Show reasoning in a temporary message |
| Show tool calls | Show tool calls in a temporary message |
| Bot language | en (default) or ru |
| Enable bot | Start or pause Telegram polling |
The token field only reports whether a token is configured. A token supplied through the environment cannot be overwritten from the page.
First run
- Create a bot with @BotFather and save its token in Settings → Telegram.
- In @BotFather open Bot Settings → Threaded mode and enable it.
- Open the bot chat, tap the bot name and enable Topics.
- Send
/start in All. With an empty allowlist the bot replies with your user and chat ids.
- Add your user id to Allowed users and press Save.
- Send
/sessions in All, choose a workspace and open or create a session.
- Send a test message in the new topic.
An ordinary message in All creates a new session topic in the default workspace. Commands such as /sessions, /fork and /last still work in All.
Plugins page
The plugin page is informational. It points to Settings → Telegram and lists the manual configuration files. Use the bundle switch there to enable or disable the plugin; Enable bot is a soft pause that keeps the plugin loaded but stops polling.
Headless profile
The bot can run without the Web UI:
mkdir -p ~/.dsh/profiles/tg
cd ~/.dsh/profiles/tg
package.json:
{
"name": "dsh-profile-tg",
"private": true,
"dependencies": { "dsh-telegram-bot": "latest" },
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "dsh-telegram-bot"]
}
}
}
cordis.patch.yml:
- id: telegram-bot
name: dsh-telegram-bot
config:
enabled: true
allowedUsers: ["<user-id>"]
allowedChats: ["<chat-id>"]
Install and run:
npm install
printf 'TELEGRAM_BOT_TOKEN=%s\n' '<token>' >> ~/.dsh/.env
chmod 600 ~/.dsh/.env
npx @deepseek-ai/dsh --profile tg
Do not put the token in cordis.patch.yml.
Security
- The bot token lives in the credential store, not in the profile patch.
- Empty Allowed users answers only in private chats with the setup hint.
- Group and channel chats require an entry in Allowed chats.
- Do not run two pollers with the same token; Telegram returns
409 Conflict.
- A DSH plugin runs in-process with the Host. Install only source you trust.
Development
No build step is needed.
npm install
node --check index.js
node --check client.js
npm test
index.js is the Host half: Telegram polling, topic routing and the session bridge. client.js registers the Settings page and the Plugins-page note. The plugin adds no model-facing tools or system-prompt text; it connects Telegram to the existing DSH agent.
License
MIT
Credits
Markdown to Telegram formatting uses telegramify-markdown (MIT).
