# Telegram Bridge

The Telegram bridge is a scoped public ingress and egress layer. It supports admin DMs, admin group mode, public group mode, media intake, generated artifact return, scoped memory, and persona documents.

## Start And Configure

```text
/telegram --key <bot-token>
/telegram --admin <telegram-user-id>
/telegram
/telegram status
/telegram stop
```

## BotFather Setup

1. Create the bot with BotFather and save the token through `/telegram --key <bot-token>`.
2. Disable privacy mode if the bot must read all group messages; leave privacy mode on if it should only see commands, mentions, and replies.
3. Add the bot to the target group and grant only the permissions it needs.
4. Send `/telegram --admin <telegram-user-id>` from the TUI before enabling public contexts.
5. Run `/telegram status` and verify bot username, admin user, mode, and connected chats.

## Access Matrix

| Context | Read Messages | Send Messages | Tools | Memory Scope |
| --- | --- | --- | --- | --- |
| Admin DM | yes | yes | admin policy | admin user |
| Admin group | replies, mentions, or all messages depending on BotFather privacy | only if Telegram grants send rights | configured group policy | group plus sender |
| Public group | scoped public intake | only if Telegram grants send rights | creative/public policy | group plus sender |
| No send rights | observed incoming messages only | no | no outbound retry loop | failure noted for that chat |

If Telegram returns a send failure, store the raw failed tool output in the conversation trajectory. The agent should reason from the observed failure and avoid repeated sends to a chat where it lacks rights.

## Scope Model

Telegram context must preserve:

- chat ID
- user ID
- sender identity
- reply target
- media references
- group versus private scope

The agent must not collapse every participant into "the user." Persona and preference state is scoped by user and by group.

## Reply Preferences

Supported preference modes:

- quick full-context reply first, then notes after
- notes first, reply after
- simple rapid reply with tools and context but no extra notes stage

Preferences should be stored only when a user explicitly expresses a preference or an admin configures one. They should live in persona/state docs for that user or group scope.

| Mode | Behavior |
| --- | --- |
| `reply-first` | send the reply with full context first, then store notes/reflection after |
| `notes-first` | store notes/reflection first, then send the reply |
| `rapid` | reply with current tools and context, no extra notes stage |

Preference writes require an explicit tool decision. They are not selected by regex or chat heuristics.

## Failure Feedback

Telegram platform and tool failures should be passed back to the agent loop as raw observed output. Do not hardcode behavior around a specific Telegram error string. The model should see the observed failure and choose a corrected action.

Failure feedback should include:

- attempted method and destination chat ID
- Telegram API error object as returned
- message or media type attempted
- whether the failure happened before or after content generation
- current chat/user preference scope

The feedback is ordinary trajectory evidence. It should not be converted into reward hacks, hidden classifiers, or error-specific branches.

## Public Creative Tools

Public users can create files, images, and audio through scoped creative workspaces under:

```text
.omnius/telegram-creative/<chat>/
```

These tools should not grant arbitrary filesystem access.

## Media Intake

Photos, documents, audio, video, and voice messages should be downloaded, summarized, scoped, and linked into memory with sender/message/reply metadata where enabled.

## Verification

Relevant focused tests include Telegram delivery preferences, inference error suppression, reflection corpus, and Bot API compatibility tests.