@syncended/dsh-messenger

DSH configuration

The package exports cordis.patch.yml as its DSH bundle and a Web client plugin. The Telegram adapter is disabled by default, so installation never starts a bot before credentials and access controls are configured.

Configure in DSH Web

1. Restart the Web profile after installing or upgrading the package.
2. Open Settings → Messengers → Telegram.
3. Enter the token issued by BotFather. It is written directly to the DSH credential store and never saved in plugin settings.
4. Add at least one allowed numeric Telegram chat ID.
5. Keep Allow private chats only enabled unless group access is required. For groups, add explicit allowed operator user IDs as well.
6. Turn on Enable Telegram adapter and save.
7. Send /start to the bot, then choose Sessions or New.

Settings changes apply live after the initial plugin restart. Local reverse-proxy origins under the reserved .localhost suffix, for example https://dsh.localhost, are supported; requests still pass through the DSH Host API trust fence. A bot token can also come from the TELEGRAM_BOT_TOKEN environment variable of the process launching dsh web; environment-provided credentials are intentionally read-only in the Web page.

Find Telegram chat and user IDs

Before enabling this plugin's poller, send a message to the bot and call Telegram's official getUpdates endpoint once:

curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates"

Use result[].message.chat.id as an allowed chat ID and result[].message.from.id as an allowed operator user ID. Group chat IDs are normally negative. Do not paste bot tokens into third-party “ID finder” bots or websites.

If getUpdates reports a webhook conflict, remove the webhook through the official Bot API before enabling long polling. In groups, review BotFather privacy mode: with privacy mode enabled, Telegram sends the bot commands and directed messages rather than every ordinary group message.

Configure manually

The same settings can be supplied by editing the existing messenger row in $DSH_HOME/profiles/web/cordis.patch.yml (normally ~/.dsh/profiles/web/cordis.patch.yml). Do not add a duplicate row with the same id:

- id: messenger
  config:
    telegram:
      enabled: true
      tokenRef: TELEGRAM_BOT_TOKEN
      allowedChatIds:
        - '123456789'
      allowedUserIds: []
      privateChatsOnly: true
      pollTimeoutSeconds: 30
      requestTimeoutMs: 15000

tokenRef contains only the reserved DSH credential reference TELEGRAM_BOT_TOKEN; the secret value belongs in the managed DSH credential store or an environment variable with that name. Other references are rejected. Restart the Host after manual YAML edits; Web settings changes apply live.

Important: the adapter is disabled by default and cannot be enabled until at least one allowed chat ID is configured. Group chats are disabled by default; to enable them, set privateChatsOnly: false and explicitly list authorized operators in allowedUserIds.

Operator trust model

Every authorized Telegram operator is trusted as a Host-wide DSH operator. They can discover and resume top-level sessions, create sessions, send prompts and steering, change model/reasoning selection, change the session's DSH permission preset, cancel work, and receive assistant output. danger-full-access requires a second Telegram confirmation, but it is still a powerful Host-side mode. Prefer workspace-write and use a private bot chat.

In a group, mirrored output is visible to every group member even though only IDs in allowedUserIds can issue commands. Use groups only when every participant may see the connected session.

Inline callback payloads contain only opaque random one-use IDs. Ordinary control actions are held in process memory for ten minutes; question options can remain valid for up to 24 hours. Every action is bound to the originating transport, chat, operator, target session, and binding revision. Session IDs, paths, permission payloads, tool arguments, and credentials are not placed in Telegram callback data.

The credential reference is fixed to TELEGRAM_BOT_TOKEN so the plugin cannot resolve, overwrite, or remove credentials owned by another integration. Token values are checked for Telegram bot-token syntax before requests are sent.

Delivery and latency semantics

Inbound updates use explicit at-most-once delivery. The adapter confirms an entire fetched batch with Telegram before scheduling any DSH side effect. Updates returned by that confirmation request are retained as the next batch rather than discarded. A process crash after confirmation can therefore require the operator to resend an update, but prompts and cancellations are not replayed automatically.

Long-poll timeout does not add command latency: Telegram returns a waiting poll immediately when an update arrives, and zero-time confirmation calls use only requestTimeoutMs. Poll, confirmation, handler, and Bot API failures are logged; Telegram retry_after is honored. Confirmed process-local work is capped at 64 handlers; polling applies backpressure before confirming another batch. Per-chat message handlers keep deterministic order, while callback acknowledgements bypass blocked chat tails and their substantive actions remain serialized.

Troubleshooting

• An enabled setting is not proof of connectivity. Check Host logs for token validation, DNS/TLS, webhook conflict, polling, and Bot API failures.
• If messages are ignored, verify the numeric chat ID and, for groups, the sender's allowed user ID and privateChatsOnly setting.
• If polling reports a conflict, stop the other poller or remove the active webhook.
• If the Web page cannot write settings or credentials, connect directly to the Host or through a supported same-origin .localhost reverse proxy.