dsh-telegram-bot

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.

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

1. Create a bot with @BotFather and save its token in Settings → Telegram.
2. In @BotFather open Bot Settings → Threaded mode and enable it.
3. Open the bot chat, tap the bot name and enable Topics.
4. Send /start in All. With an empty allowlist the bot replies with your user and chat ids.
5. Add your user id to Allowed users and press Save.
6. Send /sessions in All, choose a workspace and open or create a session.
7. 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).