Metadata-Version: 2.4
Name: waken-telegram
Version: 0.1.0
Summary: Telegram Source/Output for Waken — long-polling in, sendMessage out.
Project-URL: Homepage, https://github.com/WakenHQ/waken-telegram
Project-URL: Repository, https://github.com/WakenHQ/waken-telegram
Project-URL: Issues, https://github.com/WakenHQ/waken-telegram/issues
Project-URL: Documentation, https://github.com/WakenHQ/waken-telegram/tree/main/docs
Author: Waken contributors
License: MIT
License-File: LICENSE
Keywords: agents,ai,telegram,waken
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: python-telegram-bot>=21.0
Requires-Dist: waken>=0.1.1
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# waken-telegram

[![CI](https://github.com/WakenHQ/waken-telegram/actions/workflows/ci.yml/badge.svg)](https://github.com/WakenHQ/waken-telegram/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)](https://github.com/WakenHQ/waken-telegram/blob/main/LICENSE)

Telegram `Source`/`Output` for [Waken](https://github.com/WakenHQ/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
`Event`s) and an `Output` (delivers a `Response` back to the chat it came
from), not a `Target`.

## Install

```bash
pip install waken-telegram
```

Set `TELEGRAM_BOT_TOKEN` in your environment — get one from
[@BotFather](https://t.me/BotFather).

## Usage

```python
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

```bash
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](https://github.com/WakenHQ/waken-telegram/blob/main/LICENSE)
