telegram.md

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 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
                                                          │
                           access gate — allow-list (AllowedUsers; empty = nobody)
                           or first message = shared access PIN → enrolled + welcome
                                                          │
                              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).
• Closed by default. Only the users listed in AllowedUsers (numeric Telegram id or @username) can talk to the agent. Empty = nobody — a stranger who finds the account is ignored until they authenticate.
• Enrollment with the access PIN. An unlisted user who sends the access PIN — the same PIN used for SIP calls (Sip:Pin, changed from the TUI with /sip config set Pin; the two mediums share one PIN and one attempt/lockout budget) — is added to AllowedUsers automatically and receives the same welcome used after a SIP login, as text ("How can I help you?"). Wrong PINs count against the shared gate and can lock the PIN out machine-wide for the configured hours. No PIN configured = the enrollment path is disabled (allow-list only).
• 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, PersistentData\telegram.json — separate from PersistentData\appsettings.json on purpose, and never touched by updates (see 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) stored under PersistentData\. 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 = nobody (closed by default): users enroll by sending the access PIN (see above) or are added from the TUI
Agent	"default-agent"	Agent set used for the conversations (see AgentTools.Resolve)

Access PIN. Telegram shares the external-client access PIN with SIP: set it once with /sip config set Pin <code> (shown masked as Sip:Pin in the appsettings config). The PIN gate is machine-wide — wrong attempts from SIP and Telegram accumulate and a lockout blocks both for Sip:LockoutHours.

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.