📦 @goodandready/dsh-messenger-gateway
Telegram Messenger Bridge with Interactive Buttons, Forum Topics & Voice Notes for DeepSeek Harness
🇬🇧 English •
🇷🇺 Русский •
🇨🇳 中文说明
⭐ If you like this plugin, please star it on GitHub — it shows me that the plugin is useful to you and motivates me to keep developing it.
🐛 If you find a bug or would like to request a feature, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
|
⚡ Overview
dsh-messenger-gateway provides an enterprise-grade, multi-transport messaging gateway for DeepSeek Harness agents.
Talk to your Harness agent directly from Telegram: interactive keyboard buttons, forum topic sessions, private user workspaces, pairing codes, and optional spoken voice replies.
Talk to your Harness agent from Telegram: text, voice, photos, documents, inline buttons, named homes, and optional spoken replies.
Features
- Long-poll or webhook Telegram bot
- Multi-transport support: Telegram, Discord (Webhooks & Bot API), and Slack (Webhooks & Bot API)
- Allowlist + pairing codes
- Per-user or per-chat sessions (
sessionScope)
- Forum topics as separate sessions
- Quick actions reply keyboard (
/keyboard on|off)
- Multi-select interactive ask forms with checkboxes and pagination (
messenger_ask)
- Artifact & Mermaid diagram rendering (SVG cards) and monospace table formatting
- Agent roles & personas (
/role coder, /role architect, @role tags in group chats)
- Agent tools & skills inspection (
/skills, /tools)
- Session management: dialogue history export to Markdown (
/export), turn rewind (/rewind), session branching (/fork)
- Workspace file manager (
/files [dir]) and file download (/get <path>) with directory traversal protection
- Admin alert channel for pairing requests, model errors and monitoring (
/setalert, /alert)
- Persistent scheduled reminders (
/remind <time> <text>, /remind list, /remind cancel)
- Inbound webhook event dispatcher (
POST /dsh-messenger-gateway/events) for CI/CD and external alerts
- Steer: follow-up messages while the agent is busy (instead of aborting)
/stop, /new, /model, /status, /voice, /sethome, /home- Agent tool
messenger_ask (inline keyboard answers return to the agent)
- Named homes for outbound notify /
messenger.send
- Optional notify bridge: web session events → Telegram home (excludes messenger sessions)
- Inbound voice → STT (
dsh-voice), photos → vision (dsh-vision-bridge)
- Optional TTS replies (
dsh-tts); mp3 is converted to OGG/Opus via ffmpeg for Telegram voice notes
Discord and Slack adapters are available as outbound transports (Webhooks or Bot REST APIs).
Install
dsh plugin --profile web add @goodandready/dsh-messenger-gateway
Then open Settings → Plugins → Messenger gateway:
- Enable Telegram
- Paste the BotFather token (write-only; leave blank to keep the current token)
- Set allowed Telegram user IDs (or use pairing)
Optional companion plugins (same profile)
| Plugin | Role |
|---|
@goodandready/dsh-voice | Transcribe inbound voice messages |
@goodandready/dsh-tts | Speak agent replies |
@goodandready/dsh-vision-bridge | Describe inbound photos |
They are not npm dependencies of this package — install them separately if you want those features.
Voice notes
Spoken replies use Telegram sendVoice. If TTS returns MP3 (or other non-Opus audio), the gateway runs ffmpeg (libopus) to produce OGG. If ffmpeg is missing or conversion fails, the audio is sent as a regular audio file instead of a voice note.
Commands (Telegram)
| Command | Description |
|---|
/start /help | Help |
/whoami | Your Telegram user id |
/new | New agent session |
/stop | Abort the current turn |
/model | Interactive 2-step model picker (providers → models) or /model <prov> <mod> |
/status | Gateway status and session counters |
/top | Live server resources: RSS/Heap memory, uptime, active chats, reminders |
/topic <name> | Create a new Telegram forum topic in supergroups and start an isolated session |
/role [name] | Switch agent persona (coder, architect, reviewer, writer, translator, concise) |
/skills /tools | List active agent tools and capabilities |
/fork | Fork current session into a new independent session |
/export | Export session dialogue history to Markdown |
/rewind [N] | Rewind last N conversation turns |
/files [dir] | Workspace file manager |
/get <path> | Download file from workspace |
/remind <time> <text> | Set a reminder (e.g. /remind 15m Call client) |
/setalert /alert | Configure admin alert channel and send test alert |
/keyboard on|off | Toggle quick actions reply keyboard |
/voice on|off | Per-user spoken replies |
/tts on|off|status | Per-chat spoken replies |
/sethome [name] | Bind current chat/topic as a named home |
|
Multi-Transport Support (Discord & Slack)
In addition to Telegram, outbound messages can be dispatched to Discord and Slack via Webhooks or Bot APIs:
- Discord: set
discord.enabled: true, provide either webhookUrl or botToken. Target channels via chatId: "<channel_id>".
- Slack: set
slack.enabled: true, provide either webhookUrl or botToken. Target channels via chatId: "<channel_id>" or threads via threadId: "<thread_ts>".
Agent tools & HTTP
- Tool:
messenger_ask — ask the user with inline buttons; choice is fed back into the turn
- HTTP (when enabled):
/messenger/send, /messenger/ask, /messenger/progress
- Cordis service:
ctx.messenger for other plugins
Configuration notes
sessionScope: user (default) or chat — how group chats isolate sessionsvoiceMode: mirror / always / off — when to speak replies (also /voice)tts.enabled / tts.maxChars — TTS gate and length capnotifyBridge — forward non-messenger web session events to a home- Bot token is a DSH secret field — never commit it
Client UI & Settings Card
- Mounted into
settings.plugin.item on the Plugins tab (key: dsh-messenger-gateway).
- Configuration is managed reactively via
settingsScope.bind({ namespace: 'dsh-messenger-gateway' }) with snapshot status checking (loading, unavailable, ready).
- Protected dictionary registration: duplicate registration attempts on page reload are safely caught with non-fatal warnings, ensuring the settings card never fails to mount.
Requirements
- DeepSeek Harness web (or compatible) profile
- Node.js matching your Harness install
- For voice notes from non-Opus TTS:
ffmpeg on the host PATH
License
MIT
