waken-telegram

Telegram Source/Output for Waken — long-polling in, sendMessage out.

Unlike waken-claude/waken-openai/... (Target adapters wrapping an AI-agent backend), this package plugs into the other end of the runtime: Telegram is a channel, so it ships a Source (turns incoming messages into Events) and an Output (delivers a Response back to the chat it came from), not a Target.

Install

pip install waken-telegram

Set TELEGRAM_BOT_TOKEN in your environment — get one from @BotFather.

Usage

from waken import Runtime, target_fn, Event, Response
from waken_telegram import TelegramSource, TelegramOutput

@target_fn
async def echo(event: Event) -> Response:
    return Response(text=event.payload["prompt"])

runtime = Runtime()
runtime.target("echo", echo)
runtime.source("telegram", TelegramSource(target="echo"))
runtime.output("telegram", TelegramOutput())
runtime.run()

Message a bot registered under TELEGRAM_BOT_TOKEN and it replies through the same chat — TelegramSource stashes the chat's id on Event.metadata["chat_id"], and TelegramOutput reads it back off to know where to send the response.

Design notes

• Long polling, not webhooks. TelegramSource calls Bot.get_updates in a background loop rather than standing up a webhook receiver — no public HTTP endpoint, no signature-verification story. It also sidesteps a real limitation in core waken's webhook route today: it only passes handlers the parsed JSON body, with no request headers, which blocks any signature-verified webhook flow. That's a gap in waken core, not something worked around here.
• Sessions are keyed by the Telegram chat_id via runtime.session("telegram", str(chat_id)), so a Target sees the same session_id across a chat's messages.
• Text messages only, by design. Photos, stickers, voice notes, and every other Telegram message type are ignored in v1 — a deliberate scope boundary, not an oversight. Extending TelegramSource._poll_once to branch on more Message fields is the natural next step if you need it.

Development

git clone https://github.com/WakenHQ/waken-telegram
cd waken-telegram
pip install -e ".[dev]"
pytest

Tests mock telegram.Bot entirely — no network access or real bot token needed to run the suite.

License

MIT