Telegram Search: scoped access and temporary image URLs
Review Telegram Search v1.6.0 migration, method and chat grants, audit persistence and five-minute media URLs before an authorized AI-agent integration.
Decide whether the agent needs text or an attachment
Migrate the server policy without changing the client variable
A method grant is not a chat grant
Audit persistence is part of the response path
Decide whether the agent needs text or an attachment
Telegram Search provides a search and retrieval interface around an operator’s Telegram data. Its CLI does not perform the AI analysis itself. For an agent integration, begin with the permitted data and recipient: searching an approved chat, reading one message and sharing an image with a model are separate decisions. This guide reviews public v1.6.0 documentation and tagged code on October 17, 2026. We did not install the project, access a Telegram account, issue credentials or temporary links, or run its tests. It is not a live integration test or a security audit.
| Task | Interface to review | Boundary to retain |
|---|---|---|
| Search selected indexed chats | A remote query/search method with specific chat grants | The local index is not a live recheck of Telegram membership. |
| Read an attachment already stored by the server | Explicit local media source | Local means the remote server’s bytes, not files on the agent’s computer. |
| Fetch a current Telegram attachment | Explicit telegram media source | Requires an authorized active account runtime on the server. |
| Give a model one permitted image | A temporary media link and the provider’s supported image input | The recipient, content and transfer need authorization before sharing. |
Migrate the server policy without changing the client variable
v1.5.0 introduced temporary attachment URLs on October 17 at 13:00:15 UTC. v1.6.0 followed at 13:44:57 UTC with scoped remote access. The tagged configuration parser reads TG_SEARCH_REMOTE_ACCESS; the old server-side TG_SEARCH_REMOTE_TOKEN and TG_SEARCH_REMOTE_ACCOUNT_ID pair does not enable the remote API. A crucial shape detail: although PR #681’s summary calls the policy an array, the v1.6.0 parser and server README require a JSON object containing a credentials array. Use the tagged implementation when planning a migration.
| Location | Field or change | What it means |
|---|---|---|
| Server | TG_SEARCH_REMOTE_ACCESS | Object with a credentials array; absent policy leaves remote access disabled. |
| Each credential | id, accountId, capabilities, chatPermissions, optional expiresAt | IDs follow the documented database identity format; expiry uses Unix milliseconds. Method and chat grants are separate. |
| Client | TG_SEARCH_REMOTE_TOKEN | Remains the client’s bearer-token variable; it is not replaced by the server policy JSON. |
| Database | 0038_remote-access-audit-log.sql | Adds remote_audit_events. The earlier v1.5.0 note about no migration does not describe the v1.6.0 upgrade. |
A method grant is not a chat grant
The tagged remote handler checks the exact method capability and the requested chat scope. A credential allowed to call media.createLink still needs read access to the selected chat. Missing method permission is not repaired by granting more chats. For a selected-chat credential, omitted chat filters are narrowed to its readable chats; a request mixing allowed and disallowed chats fails instead of silently returning a partial result. The server selects the configured account, not an account supplied in the request. Treat wildcard chat grants as broader access requiring a separate decision, not a convenient default.
Audit persistence is part of the response path
The authenticated POST method handler awaits its sanitized audit record before returning a result, and an audit write failure prevents the normal response. The migration creates the remote_audit_events table. Search summaries retain a query length and SHA-256 hash rather than raw search text; the audit design excludes tokens and message bodies. This does not mean arbitrary application, proxy or model-provider logs are safe to retain. Our source inspection does not establish production log behavior. The anonymous media-download GET/HEAD route is distinct from that authenticated POST audit path.
Keep the rest of the server inside its own access boundary
The server README limits these access checks to /v1/remote/*. They do not add authorization to /ws, /v1/photos/* or /v1/stickers/*. A configured remote policy therefore does not secure the entire web/media server. The documentation also preserves compatibility for legacy private-message rows with NULL ownership; it explicitly does not promise tenant isolation for those databases. Review the complete ingress and historical data ownership before an authorized rollout. Do not expose unrelated routes merely to make an integration reachable.
A five-minute media URL is a temporary access credential
media.createLink checks the issuing request’s method and chat grants, then returns a relative path, expiry and attachment metadata. The CLI combines that path with its trusted remote endpoint. The resulting URL can return the attachment without an Authorization header, so anyone holding it can use it during its lifetime. Five minutes limits new requests; it does not erase a downloaded copy or guarantee deletion by a model provider. Keep the full URL out of ordinary reports, screenshots, chat transcripts and logs.
| Property | Documented behavior | Integration implication |
|---|---|---|
| Size | 10 MiB default whole-file budget; 50 MiB maximum | A valid link is not a promise that the model accepts that file size or format. |
| Source | local uses server-stored photos/stickers; telegram explicitly retrieves current authorized media | No automatic source switch; unsupported local attachments return an error. |
| Response | Original complete bytes; no transcoding or advertised range support | An animated sticker is not automatically converted into a model-readable still image. |
| Transfer | Up to two active transfers/buffers per credential per server process; a sixty-second deadline | Capacity is per process. A transfer admitted before link expiry still has its own deadline. |
Do not confuse bearer expiry with ticket expiry
In the tagged code, credential expiry is checked when authenticating a POST request. The media-download handler instead decrypts and checks its attachment ticket and the ticket’s own expiry. It does not repeat the POST method/chat authorization checks. Therefore, do not assume that a later bearer expiry or narrower grant alone proves a previously issued link is unusable. The documentation identifies rotation of the issuing credential as invalidating its links; an operator must apply the relevant policy consistently across replicas. This is an observation of the tagged code path, not a revocation test we performed.
Place an authorized image URL in an image input
The CLI documentation says to pass a PNG/JPEG URL through the model provider’s image input field. Pasting a URL into prompt prose does not itself load the image. Check the chosen provider’s supported inputs, size limits and retention terms before transfer. A cloud model also cannot retrieve a localhost or private-network endpoint merely because your own computer can. The CLI does not publish that endpoint. If the permitted route is unreachable, stop or choose an independently authorized transfer method; do not make private chats or server routes public as a workaround.
Use an inert design example before any live trial
An illustrative endpoint is https://tgs.example.invalid. The dummy ticket value is INERT_EXAMPLE. These are deliberately nonfunctional placeholders, not a working link or credential. A design review can map the authorized chat and attachment, source choice, expected recipient, image-input field, expiry handling and redaction requirements without creating a real link. Before a live trial, the responsible owner should approve the specific data and model destination. Authentication to Telegram alone does not authorize sending its private conversations or images to another service.
Separate maintainer validation from your deployment evidence
PR #681 reports lint, type and unit-test validation and says no deployment or live Telegram account was used. Those are maintainer-reported results, not tests run by uAgentKit, and they do not establish live account behavior or a security certification. For a later authorized pilot, record the exact server/CLI versions, applied database migration, grants, selected source, denied-scope behavior, audit-write failure handling and link lifecycle. Use synthetic or expressly authorized material, retain failures and redact secrets. The workflow-building and evaluation guides below help turn that record into a bounded acceptance decision.
Continue your comparison
Plan agent workflow building →
Define a small agent evaluation →
Sources supporting this guide
- Telegram Search v1.6.0 release
Telegram Search maintainers · github.com · Read · 2026-10-17
- Telegram Search v1.5.0: temporary attachment URLs
Telegram Search maintainers · github.com · Read · 2026-10-17
- v1.6.0 server README: access, media and security boundary
Telegram Search maintainers · github.com · Read · 2026-10-17
- v1.6.0 CLI README: remote clients and image inputs
Telegram Search maintainers · github.com · Read · 2026-10-17
- Tagged remote configuration, scope and audit handler
Telegram Search maintainers · github.com · Read · 2026-10-17
- Tagged media-ticket lifetime and download handler
Telegram Search maintainers · github.com · Read · 2026-10-17
- v1.6.0 audit-table migration
Telegram Search maintainers · github.com · Read · 2026-10-17
- PR #681: maintainer-reported validation and limitations
Telegram Search maintainers · github.com · Read · 2026-10-17
Research method & original evidence · Who operates uAgentKit · Commercial disclosure