| # Telegram chat — AgentBridge as a Telegram chat client |
|
|
| AgentBridge can connect to Telegram **as a user account** (a "userbot") and act like any |
| other chat client you already support (the TUI, the HTML/Giraffe web client): people write |
| to your account in a **private chat**, the message (text and/or file attachments) is handed |
| to the agents, and the reply — text plus any files the agent attaches — comes back into the |
| same chat. |
|
|
| This is **text chat with attachments only**. The Telegram Client API (MTProto) does not |
| support audio calls, so Telegram is **not** a voice medium: the media list stays |
| **SIP (phone calls) and Voice (desktop microphone)** — Telegram adds a chat client, nothing |
| more. The transport is the [WTelegramClient](https://github.com/wiz0u/WTelegramClient) |
| library (userbot, MTProto); no HTTP/API polling is involved. |
|
|
| ## How it works |
|
|
| ``` |
| Telegram user ⇄ private chat message (text + files) ⇄ WTelegramClient (userbot) |
| │ |
| filter: private chats only, own messages (echo) ignored |
| │ |
| allow-list gate (AllowedUsers; empty = everyone) |
| — disallowed users are silently ignored |
| │ |
| per-user FIFO queue (messages answered in arrival order) |
| │ |
| DownloadFileAsync (incoming files, ≤25 MB) → FileAttachment │ |
| │ |
| SessionStore + AgentHarness.ExecuteAction |
| (one chat session per user, 30-min idle expiry) |
| │ |
| SendMessageAsync (reply) + SendMediaAsync (agent's attachments, ≤25 MB each) |
| ``` |
|
|
| - **Private chats only.** Messages in groups/channels are ignored (as are the bot's own |
| messages, so replies never echo into an endless loop). |
| - **Allow-list (optional).** `AllowedUsers` in `telegram.json` restricts who can talk to |
| the agent (numeric user id or `@username`). **Empty = everyone** in a private chat, exactly |
| like the HTML client. Disallowed users are silently ignored. |
| - **Attachments both ways.** Incoming documents/photos are downloaded (cap 25 MB) and go |
| through the same server-side Markdown conversion as the HTML uploads (`/v1/files`), so the |
| agent reads their content. Files the agent attaches in its answer (the `done` method's |
| `"attachments"` field) are sent back as Telegram documents (cap 25 MB each). |
| - **One conversation per user.** Each user keeps a multi-turn session (history); after |
| 30 minutes of silence the session is disposed and a fresh one starts on the next message. |
|
|
| ## Configuration (`telegram.json`) |
|
|
| Telegram configuration lives in its own file, **`telegram.json` next to the executable** |
| — separate from `appsettings.json` on purpose, and never overwritten by updates (see |
| [autoupdate.md](autoupdate.md) "the file storage tiers", same protection as `providers.json`). |
| You can edit it by hand, from the TUI (`/telegram`), or with the guided setup scripts |
| (`scripts/setup-telegram.bat` on Windows, `scripts/setup-telegram.sh` on Linux/macOS — |
| English prompts, they create or update `telegram.json`). |
|
|
| | Key | Default | Description | |
| |---|---|---| |
| | `Enabled` | `false` | Master switch — the bridge starts at boot only when true | |
| | `ApiId` | built-in | App api_id — AgentBridge ships with its own app identity, no need to create one. Override to use a per-install app | |
| | `ApiHash` | built-in | App api_hash — same as above | |
| | `PhoneNumber` | `""` | Account phone number, international format (e.g. `+393331234567`) — **the only key a new deployment must set** | |
| | `SessionPath` | `"telegram.session"` | Session file (auth keys) relative to the executable dir. After the first login the session persists: no code is asked again | |
| | `AllowedUsers` | `[]` | Users allowed to talk to the agent — numeric ids and/or `@usernames`, comma-separated in the TUI. Empty = all private chats | |
| | `Agent` | `"default-agent"` | Agent set used for the conversations (see AgentTools.Resolve) | |
|
|
| ## First login (one time only) |
|
|
| The first login needs the **verification code** Telegram sends (SMS/call/other Telegram |
| app), and the 2FA password if the account has one. The TUI guides it — nothing blocks the |
| server boot, the bridge simply waits in a pending-login state: |
|
|
| ``` |
| /telegram status → phase "code" (login pending) |
| /telegram login-code 12345 → paste the code from Telegram |
| /telegram status → phase "on" (connected) |
| ``` |
|
|
| The `.session` file is written automatically; the next starts log in silently. |
|
|
| ## TUI commands |
|
|
| | Command | Meaning | |
| |---|---| |
| | `/telegram status` | Live state: enabled, phase (`off`/`conn`/`code`/`2fa`/`on`/`err`), logged-in user, allow-list, agent | |
| | `/telegram config` | Show the effective configuration (api_hash masked) | |
| | `/telegram config set <key> <value>` | Change one config key and persist it to `telegram.json` (connection keys restart the bridge) | |
| | `/telegram config reload` | Re-read `telegram.json` (hand edits made outside the TUI) and apply them | |
| | `/telegram login-code <code>` | Complete the pending login (verification code or 2FA password) | |
| | `/telegram allow <user>` | Add a user (id or @username) to the allow-list and persist | |
| | `/telegram disallow <user>` | Remove a user from the allow-list and persist | |
| |
| The status bar shows a `tg:` segment (`on` = connected, `code` = waiting for the login |
| code, ...) refreshed by the same 3-second poll as SIP. |
| |
| **Telegram is an in-process chat client — it exposes no HTTP endpoints.** The |
| `/telegram` TUI commands call the `TelegramBridge` directly in the same process; the |
| message transport is entirely the WTelegramClient library. There is nothing to configure |
| over HTTP: the configuration surface is the TUI, the setup scripts, and `telegram.json` |
| itself. |
| |
| ## Getting your api_id / api_hash |
| |
| **You normally don't need these.** AgentBridge ships with its own Telegram app identity |
| (`ApiId`/`ApiHash` compiled in) — a deployment only sets `PhoneNumber` and completes the |
| first login with the verification code. |
| |
| Override the built-in credentials **only** when you want a per-install app identity (for |
| example to keep independent deployments from sharing one app): |
| |
| 1. Open https://my.telegram.org/apps and sign in with the account you want to use. |
| 2. Create an application (any name/description — these identify *your* app, not the user). |
| 3. Put your values in `telegram.json` (`ApiId` / `ApiHash`) — they take precedence over |
| the built-in ones (or set them with `/telegram config set ApiId <id>` and |
| `/telegram config set ApiHash <hash>`). |
| |
| ## Notes and limitations |
| |
| - **A userbot, not a bot.** The bridge signs in as a real user account. Telegram's terms |
| of service apply; don't use it for spam. If you prefer a bot account, use a BotFather |
| token instead — out of scope here. |
| - **No audio.** The Telegram Client API has no audio-call support: voice messages are |
| treated as file attachments, not as a conversation medium. |
| - **Security.** The api_hash and the `.session` file are credentials: protect them like the |
| API keys in `providers.json`. The session file allows full access to the account. |
| - **Telegram sessions are per-device.** Telegram may show a new active session in the |
| account settings after the first login — normal. |
|
|
