@dual-os/telegram

Private ESM Telegram plugin for the Dual SDK. Provides chat, callback, file, and message actions plus an update webhook trigger.

Composition

// Definition-only composition: no client or handler-layer imports.
import { telegramPluginBase } from "@dual-os/telegram/definition";
// Executable composition with the existing HTTP client and handlers.
import { telegramPlugin } from "@dual-os/telegram/executable";

Run the executable value in process with DualRuntime.fromPlugin(plugin, packageJson.version); a host receives the published package from npm as a standard plugin. Importing a module starts no services, makes no requests and creates no Provider Connection.

@dual-os/telegram/plugin.json exposes declarative discovery metadata: schema version, package/plugin identity, definition/executable subpaths and named exports. The package version is the release. It can be read without executing plugin code.

The historical Telegram and TelegramClient root namespaces and explicit /Telegram and /TelegramClient subpaths remain supported. The historical root includes executable modules; use /definition for definition-only composition. Internal schema modules are not public entrypoints.

Installation and compatibility

Source builds use the exact SDK and Effect dependencies in package.json; released bundles include them and the runner, without sandbox installation. Pin exact package versions and commit the application's lockfile.

The executable uses Fetch and Node-compatible APIs. Packaging adds no new runtime restriction and does not certify a new Node runtime matrix. Supply provider credentials through the host's Provider Connection setup. Never commit credentials.

API and Agent Channel

This plugin includes the existing API Actions and Workflow Triggers plus the telegram/messages Agent Channel. Existing action/trigger IDs, schemas and API authentication methods are unchanged. The additional Channel authentication is listed at plugin level; per-action authentication subsets are intentionally deferred. Use existing API Connections for Actions/Triggers and the Channel credentials below for agent conversations. No migration of unused standalone Channel installations is provided.

Telegram Bot Channel

Telegram Bot Channel telegram/messages. Uses its own Connection (customer bot token and webhook secret); the existing @dual-os/telegram workflow integration and generated plugins are unchanged.

Deployment settings choose where (chatIds: groups or <chat>/<topic>, empty for all; directMessages), who (access, allowedSenderKeys) and when (respondTo). Private text messages always respond. With mentions, groups respond only to an explicit bot mention, a command addressed to the bot username, or a reply whose Telegram sender is this bot; all_messages responds to every group message in scope and needs privacy mode off. Numeric sender access applies to messages and /stop. Actual message_thread_id values isolate forum topics; ordinary replies share their chat. Edits, forwards, channel posts, business messages, anonymous senders, other bots and non-text messages are ignored. Attachments and arbitrary history reads are unsupported.

Output uses sendMessage, editMessageText, deleteMessage, setMessageReaction and sendChatAction. Sends have no idempotency token, so all deliveries are at-most-once. Uncertain sends are terminal unknown_completion, never automatically retried. Telegram flood control is rate_limited; the client retains retry_after, while the Channel's closed error contract carries only the code. There are no automatic HTTP retries. Reaction/edit/delete restrictions and provider errors remain failures. Reactions replace the bot's single reaction; removing a reaction clears it. Typing lasts at most five seconds; idle has no explicit clearing API and waits for expiry.

Activation checkpoints bot identity before setting an owned registration URL. Telegram allows one webhook per bot: activation replaces the previous integration. Cleanup deletes only the exact URL owned by that activation and keeps queued updates. Telegram offers no conditional delete, so this follows its getWebhookInfo/deleteWebhook ownership check. Use a dedicated bot per Channel installation.

Public imports: definition-only telegramPluginBase from /definition, executable telegramPlugin from /executable or /Telegram, and Telegram.telegramPlugin from the package root. Existing API client exports remain unchanged.