omadiaomadia.ai
registry
channelchannel.telegram

Telegram Channel

@omadia/channel-telegram

Telegram als zweiter First-Class-Channel von Omadia. Spricht die Telegram Bot API direkt (kein Drittanbieter-SDK), supports Webhook + Long-Polling-Fallback, MarkdownV2-Rendering, Inline-Keyboards für Choice-Cards / Slot-Picker / Follow-Ups, Roster via getChatAdministrators für Gruppen. Self-contained — keine `depends_on`-Beziehung. Validiert die @omadia/channel-sdk Contracts gegen ein Runtime ohne Bot-Framework.

latest
v0.2.2
license
MIT
versions
9
author
byte5 GmbH

install

In your omadia instance, open Admin → Registries and add this registry, then install Telegram Channel from Admin → Plugins → Store.

registryhttps://hub.omadia.ai

setup guide

Create a Telegram bot

Telegram bots are issued by @BotFather — no developer account needed. Takes about 2 minutes.

1. Create the bot

  1. In Telegram, open the chat with @BotFather.
  2. Send /newbot → pick a display name → a unique username ending in bot.
  3. BotFather replies with the HTTP API token (123456:ABC-…). You paste this as the bot token secret during install.
  4. Optional: /setprivacy → Disable so the bot can read all group messages (otherwise only commands and @mentions).

2. Public URL vs. long-polling

  • Public HTTPS host: set Public HTTPS Base-URL to your origin (e.g. https://bot.example.com). Telegram delivers updates to <base>/api/telegram/webhook.
  • No public host (local dev): leave it empty → the bot uses long-polling (getUpdates), no tunnel needed.

3. DM policy

DM-Auth-Policy controls who may DM the bot: pairing (default — users pair via a QR deep-link first), open (anyone with the username), or disabled. Group access is handled separately when a paired operator adds the bot to a group.

versions

v0.2.2
>=1.0 <2.0181.2 KB2026-08-24
.zip8a9522a8e7d5…
v0.2.1
>=1.0 <2.0180.8 KB2026-08-18
.zipf2ebe07a46aa…
v0.2.0
>=1.0 <2.0180.8 KB2026-08-17
.zip8b722adb1de2…
v0.1.6
>=1.0 <2.0180.8 KB2026-08-17
.zip0ba8924c820a…
v0.1.5
>=1.0 <2.0180.2 KB2026-07-31
.zip77d804012eb3…
v0.1.4
>=1.0 <2.077.0 KB2026-06-03
.zip421021b457d5…
v0.1.3
>=1.0 <2.070.1 KB2026-06-03
.zip98b162d0caa0…
v0.1.2
>=1.0 <2.069.1 KB2026-05-29
.zip95f527d0783d…
v0.1.1
>=1.0 <2.069.1 KB2026-05-29
.zipddafe9e9902e…

setup fields

Values the operator fills in at install-time.

telegram_bot_tokensecret
Telegram Bot-TokenDer HTTP-API-Token, den @BotFather nach `/newbot` ausgibt (Format `123456:ABC-…`). Wird verschlüsselt im Plugin-Vault gespeichert (Vault-Key `telegram_bot_token`), nie in der installed.json-Config. Ohne Token kann der Channel nicht aktiviert werden.
required
telegram_public_base_urlstring
Public HTTPS Base-URL für den WebhookVollständige HTTPS-Origin auf der die Middleware öffentlich erreichbar ist (z.B. `https://bot.example.com`). Telegram registriert den Webhook unter `<base>/api/telegram/webhook` mit dem konfigurierten Secret-Token. Leer lassen → Plugin nutzt Long-Polling (getUpdates) als Fallback — gut für lokale dev ohne ngrok/cloudflared.
optional
dm_policystring
DM-Auth-PolicyWer darf den Bot per Direct-Message anschreiben? `pairing` (default ab S+7.6, safer): Nutzer müssen erst via QR-Deeplink-Flow gekoppelt werden, ungebundene DMs bekommen 'Bitte erst koppeln'-Reply. `open`: jeder mit dem Bot-Username darf chatten (Verhalten vor S+7.6). `disabled`: keine DMs zugelassen, Bot ignoriert silent. Group-Auth ist davon unabhängig (Auto-Allowlist beim Bot-Add durch gepairten Operator via `my_chat_member`-Event).
optional

permissions

secrets

runtime_write: true

memory

reads: [0] · writes: [0]

graph

reads: [0] · writes: [0]

network

outbound: [1]

filesystem

scratch: false