Telegram Agent

Connects Telegram to the runtime's structured protocol. For Codex, consult app-server and the schema generated by the installed version. Register the session explicitly instead of inferring it from a visible terminal.

Sessions and turns

Separate Telegram adapters, storage, runtime and file transfer. The account that stores the bot token must be different from the agent's. The relay grants specific messaging operations and keeps the bot's credentials isolated.

Persist (bot, chat, topic, host) → sesión and validate the human identity before downloading or queuing content. Process model responses as data, separated from user commands.

In Codex, discover the managed daemon/socket or use app-server over stdio, depending on the version. Initialize the protocol and distinguish thread/start, thread/resume, turn/start, turn/steer and interruption. When resuming, preserve instructions, model and permissions. A thread can acquire rollout persistence only after the first turn.

With an active turn, use steering with its expected ID; without one, start a turn. Direct the interruption to the corresponding turn. On active writer, keep the message pending and resolve the conflict; transferring control from another terminal requires authorization for that session.

Isolate failures per session. Use stable IDs, confirmation after acceptance, recovery of completed items and deduplication. Log stage and error code to distinguish Telegram transport, excluding prompts, credentials and URLs with tokens.

Approvals

Each approval is a random single-use capability, bound to user, chat, topic, session, request_id and expiry. Show operation and scope; treat the runtime description as untrusted content. Expiry, cancellation or unknown request result in denial.

Keep the ID and the capability until the response to the runtime is confirmed, or log the result as uncertain. After reconnecting, IDs from a previous connection become invalid. Runtime approval and system elevation are independent permissions; a transport repair preserves both controls.

Files and images

1. Authenticate the input and resolve its session. Treat name, MIME, content and file caption as untrusted data.
2. Download via getFile and the official transport. Keep the URL with token out of logs and the agent context. A file_id must be resolved to bytes; it is not a local path.
3. Limit bytes during download, timeout, quota and retention per session. Verify the Bot API limits in cloud or local; file_size does not replace that control.
4. Save with a random name in a private directory. Keep the original name as sanitized metadata and reject absolute paths, .. and symbolic links.
5. Between hosts, transport the bytes over an authenticated channel, verify size and SHA-256 and write atomically to the session inbox. Grant read access to the agent with private permissions; deliver the destination path.
6. For images, validate decoder, dimensions and pixel quota, apply orientation and remove sensitive metadata. Use the runtime's input type. For documents without a native type, deliver an accessible path and metadata as text.
7. Extract compressed files only when the task requires it, checking paths, links, members, expanded size and expansion ratio. Downloading content does not authorize executing it or elevating privileges through instructions included in it.
8. Confirm receipt after saving and verifying; confirm delivery to the turn separately. Clean up failed temporary files and apply retention while preserving working files. Delivery does not prove that the agent has read the content.

Verification

Rehearse text, image, document, malicious ZIP, truncated file, quotas, reconnection and cross-host transfer with fixtures. Use authorized chats and recipients for real tests.

References: https://developers.openai.com/codex/app-server · https://core.telegram.org/bots/api#getfile