Media & Stickers

Media download, custom emoji, premium asset, and sticker commands.

Media & Sticker Commands

Media download, custom emoji, premium asset, and sticker commands.

Handler group source

  • Handler module: backend/tg_client/dialogs/commands/handlers/media.py
  • Registered commands: 5
  • Registry integration: backend/tg_client/dialogs/commands/registry.py

Command index

Command Handler Service / callable Success event(s) Notes
`download_file` handle_media_commands media_command_service.download_file download_file, media_ready Immediate success is only an acknowledgement payload. The final resolved file payload is published later by media_loader.py as media_ready.
`get_custom_emoji_media` handle_media_commands media_command_service.get_custom_emoji_media get_custom_emoji_media, media_ready Immediate success is only an acknowledgement payload. Resolved emoji assets are published later as media_ready.
`get_recent_stickers` handle_media_commands sticker_service.get_recent_stickers get_recent_stickers single logical response
`get_prem_path` handle_media_commands bootstrap_service.get_premium_emoji_asset get_prem_path single logical response
`get_stickers_pack` handle_media_commands bootstrap_service.get_stickers_pack get_stickers_pack single logical response

Group conventions

  • Incoming client requests use the WebSocket action field and are routed into the owner runtime via publish_command().
  • Outbound success/error payloads are wrapped into chat_update live events.
  • ctx.send_response() means one logical success event plus a conventional <command>_error event on failure.
  • Manual ctx.send() branches indicate streaming or custom event emission; these commands are documented explicitly below.
  • Request field types and required flags are inferred from handler/service code because there is no formal request schema object for every command.

Command: download_file

Summary

Accept one or more media targets for async resolution and return an acknowledgement. Final file paths arrive later through media_ready.

Location in code

  • Handler: backend/tg_client/dialogs/commands/handlers/media.py::handle_media_commands (branch starts near line 18).
  • Service: backend/tg_client/dialogs/tdlib/services/media_command_service.py::download_file.
  • Raw API modules: backend/tg_client/dialogs/tdlib/api/files.py, backend/tg_client/dialogs/tdlib/api/emojis.py.
  • Normalizer / typed builder: backend/tg_client/dialogs/tdlib/normalizers/media_command_normalizer.py.

Request

Structure

{
  "action": "download_file",
  "userbot_id": 1,
  "files": [
    {
      "remote_unique_id": "AbCdEf123",
      "file_id": 123456
    }
  ],
  "source": "dialogs",
  "chat_id": -1001234567890,
  "msg_id": 99112233
}

Request variants

  • Preferred batch form: files: [{"remote_unique_id": "...", "file_id": 123}].
  • Cloud-only lookup: remote_unique_ids: ["..."] or remote_unique_id: "...".
  • Telegram fallback by file id: file_ids: [123, 456] or file_id: 123.
  • Legacy-compatible aliases still accepted by current code: media, remote_ids, remote_id, remote.

Parameters

Field Type Required Default Description
files `object array<object>` conditional — Preferred target form. Each item may contain remote_unique_id and/or file_id.
media `object array<object>` conditional — Legacy-compatible alias for files still accepted by current code.
remote_unique_ids array<string> conditional — Cloud-only lookup by remote unique ids.
remote_unique_id `string object` conditional — Single remote unique id lookup.
file_ids array<integer> conditional — Fallback Telegram file ids when a remote unique id is not available.
file_id integer conditional — Single fallback Telegram file id.
source string optional dialogs Source label propagated into the async download task.
extra object optional — Free-form extra metadata passed to the async loader.
chat_id integer optional — Forwarded into loader metadata when present.
msg_id integer optional — Forwarded into loader metadata when present.
message_thread_id integer optional — Forwarded into loader metadata when present.

Response variants

  • Success event(s): download_file, media_ready.
  • Error event(s): download_file_error.
  • Result shaping: backend/tg_client/dialogs/tdlib/normalizers/media_command_normalizer.py.
  • Notes: Immediate success is only an acknowledgement payload. The final resolved file payload is published later by media_loader.py as media_ready.

Errors

Error Type/Code When happens Notes
remote_unique_id, remote_unique_ids, files or file_id is required string Service-side validation or branch guard Returned as the error field of the error event.
TDLib / transport error string Raw API call fails or TDLib raises in the transport wrapper Forwarded from TdlibBaseClient.tg_call() or returned by the service.

Flow

  • TDLibListChatsConsumer.receive_json() forwards the WebSocket action into publish_command().
  • AccountOwnerWorker receives the command envelope and invokes dispatch_command_payload().
  • Registry handler handle_media_commands processes download_file.
  • Service layer executes backend/tg_client/dialogs/tdlib/services/media_command_service.py::download_file.
  • Raw TDLib wrapper(s): backend/tg_client/dialogs/tdlib/api/files.py, backend/tg_client/dialogs/tdlib/api/emojis.py.
  • Result normalization / shaping: backend/tg_client/dialogs/tdlib/normalizers/media_command_normalizer.py.
  • Final payload is emitted through ctx.send() / ctx.send_response() -> send_ws() -> live event publisher.
  • The service deduplicates targets by remote_unique_id or file_id before enqueuing work.
  • enqueue_async_file_download(...) uses cache/cloud lookup first and only downloads from Telegram when allowed and a file id is available.
  • Sibling commands in this handler group: get_custom_emoji_media, get_recent_stickers, get_prem_path, get_stickers_pack.

Notes

  • The service deduplicates targets by remote_unique_id or file_id before enqueuing work.
  • enqueue_async_file_download(...) uses cache/cloud lookup first and only downloads from Telegram when allowed and a file id is available.

Command: get_custom_emoji_media

Summary

Accept one or more custom emoji ids for async media resolution and return an acknowledgement. Final asset payloads arrive later through media_ready.

Location in code

  • Handler: backend/tg_client/dialogs/commands/handlers/media.py::handle_media_commands (branch starts near line 30).
  • Service: backend/tg_client/dialogs/tdlib/services/media_command_service.py::get_custom_emoji_media.
  • Raw API modules: backend/tg_client/dialogs/tdlib/api/files.py, backend/tg_client/dialogs/tdlib/api/emojis.py.
  • Normalizer / typed builder: backend/tg_client/dialogs/tdlib/normalizers/media_command_normalizer.py.

Request

Structure

{
  "action": "get_custom_emoji_media",
  "userbot_id": 1,
  "custom_emoji_ids": [
    "5393021912655030923"
  ]
}

Request variants

  • Batch form: custom_emoji_ids: ["5393021912655030923", "..."].
  • Single-id form: custom_emoji_id: "5393021912655030923".

Parameters

Field Type Required Default Description
custom_emoji_ids array<string> conditional — Preferred batch form for custom emoji ids.
custom_emoji_id string conditional — Single custom emoji id.

Response variants

  • Success event(s): get_custom_emoji_media, media_ready.
  • Error event(s): get_custom_emoji_media_error.
  • Result shaping: backend/tg_client/dialogs/tdlib/normalizers/media_command_normalizer.py.
  • Notes: Immediate success is only an acknowledgement payload. Resolved emoji assets are published later as media_ready.

Errors

Error Type/Code When happens Notes
custom_emoji_ids must contain at least one valid custom emoji id string Service-side validation or branch guard Returned as the error field of the error event.
TDLib / transport error string Raw API call fails or TDLib raises in the transport wrapper Forwarded from TdlibBaseClient.tg_call() or returned by the service.

Flow

  • TDLibListChatsConsumer.receive_json() forwards the WebSocket action into publish_command().
  • AccountOwnerWorker receives the command envelope and invokes dispatch_command_payload().
  • Registry handler handle_media_commands processes get_custom_emoji_media.
  • Service layer executes backend/tg_client/dialogs/tdlib/services/media_command_service.py::get_custom_emoji_media.
  • Raw TDLib wrapper(s): backend/tg_client/dialogs/tdlib/api/files.py, backend/tg_client/dialogs/tdlib/api/emojis.py.
  • Result normalization / shaping: backend/tg_client/dialogs/tdlib/normalizers/media_command_normalizer.py.
  • Final payload is emitted through ctx.send() / ctx.send_response() -> send_ws() -> live event publisher.
  • Sibling commands in this handler group: download_file, get_recent_stickers, get_prem_path, get_stickers_pack.

Command: get_recent_stickers

Summary

Get recent stickers.

Location in code

  • Handler: backend/tg_client/dialogs/commands/handlers/media.py::handle_media_commands (branch starts near line 42).
  • Service: backend/tg_client/dialogs/tdlib/services/sticker_service.py::get_recent_stickers.
  • Raw API modules: backend/tg_client/dialogs/tdlib/api/stickers.py, backend/tg_client/dialogs/tdlib/api/files.py, backend/tg_client/dialogs/tdlib/api/emojis.py.
  • Normalizer / typed builder: backend/tg_client/dialogs/tdlib/normalizers/sticker_normalizer.py.

Request

Structure

{
  "action": "get_recent_stickers",
  "userbot_id": 1,
  "is_attached": true
}

Parameters

Field Type Required Default Description
is_attached boolean optional false Derived from handler payload access in current code.

Response variants

  • Success event(s): get_recent_stickers.
  • Error event(s): get_recent_stickers_error.
  • Result shaping: backend/tg_client/dialogs/tdlib/normalizers/sticker_normalizer.py.

Errors

Error Type/Code When happens Notes
TDLib / service error string Raw API call fails or the service returns a transport-shaped error Forwarded from TdlibBaseClient.tg_call() or the service layer.

Flow

  • TDLibListChatsConsumer.receive_json() forwards the WebSocket action into publish_command().
  • AccountOwnerWorker receives the command envelope and invokes dispatch_command_payload().
  • Registry handler handle_media_commands processes get_recent_stickers.
  • Service layer executes backend/tg_client/dialogs/tdlib/services/sticker_service.py::get_recent_stickers.
  • Raw TDLib wrapper(s): backend/tg_client/dialogs/tdlib/api/stickers.py, backend/tg_client/dialogs/tdlib/api/files.py, backend/tg_client/dialogs/tdlib/api/emojis.py.
  • Result normalization / shaping: backend/tg_client/dialogs/tdlib/normalizers/sticker_normalizer.py.
  • Final payload is emitted through ctx.send() / ctx.send_response() -> send_ws() -> live event publisher.
  • Sibling commands in this handler group: download_file, get_custom_emoji_media, get_prem_path, get_stickers_pack.

Command: get_prem_path

Summary

Resolve a premium emoji asset path for one custom emoji id.

Location in code

  • Handler: backend/tg_client/dialogs/commands/handlers/media.py::handle_media_commands (branch starts near line 49).
  • Service: backend/tg_client/dialogs/tdlib/services/bootstrap_service.py::get_premium_emoji_asset.
  • Raw API modules: backend/tg_client/dialogs/tdlib/api/chats.py, backend/tg_client/dialogs/tdlib/api/profiles.py.
  • Normalizer / typed builder: backend/tg_client/dialogs/tdlib/normalizers/bootstrap_normalizer.py.

Request

Structure

{
  "action": "get_prem_path",
  "userbot_id": 1,
  "custom_emoji_id": "5393021912655030923"
}

Parameters

Field Type Required Default Description
custom_emoji_id string required — Derived from handler payload access in current code.

Response variants

  • Success event(s): get_prem_path.
  • Error event(s): get_prem_path_error.
  • Result shaping: backend/tg_client/dialogs/tdlib/normalizers/bootstrap_normalizer.py.

Errors

Error Type/Code When happens Notes
premium emoji helper is not configured string Service-side validation or branch guard Returned as the error field of the error event.
TDLib / transport error string Raw API call fails or TDLib raises in the transport wrapper Forwarded from TdlibBaseClient.tg_call() or returned by the service.

Flow

  • TDLibListChatsConsumer.receive_json() forwards the WebSocket action into publish_command().
  • AccountOwnerWorker receives the command envelope and invokes dispatch_command_payload().
  • Registry handler handle_media_commands processes get_prem_path.
  • Service layer executes backend/tg_client/dialogs/tdlib/services/bootstrap_service.py::get_premium_emoji_asset.
  • Raw TDLib wrapper(s): backend/tg_client/dialogs/tdlib/api/chats.py, backend/tg_client/dialogs/tdlib/api/profiles.py.
  • Result normalization / shaping: backend/tg_client/dialogs/tdlib/normalizers/bootstrap_normalizer.py.
  • Final payload is emitted through ctx.send() / ctx.send_response() -> send_ws() -> live event publisher.
  • Sibling commands in this handler group: download_file, get_custom_emoji_media, get_recent_stickers, get_stickers_pack.

Command: get_stickers_pack

Summary

Search or page grouped sticker-pack results through the bootstrap service.

Location in code

  • Handler: backend/tg_client/dialogs/commands/handlers/media.py::handle_media_commands (branch starts near line 56).
  • Service: backend/tg_client/dialogs/tdlib/services/bootstrap_service.py::get_stickers_pack.
  • Raw API modules: backend/tg_client/dialogs/tdlib/api/chats.py, backend/tg_client/dialogs/tdlib/api/profiles.py.
  • Normalizer / typed builder: backend/tg_client/dialogs/tdlib/normalizers/bootstrap_normalizer.py.

Request

Structure

{
  "action": "get_stickers_pack",
  "userbot_id": 1,
  "query": "party",
  "limit": 20,
  "offset": 0
}

Parameters

Field Type Required Default Description
query string optional — Derived from handler payload access in current code.
limit integer optional 20 Derived from handler payload access in current code.
offset integer optional 0 Derived from handler payload access in current code.
with_lottie boolean optional false Derived from handler payload access in current code.

Response variants

  • Success event(s): get_stickers_pack.
  • Error event(s): get_stickers_pack_error.
  • Result shaping: backend/tg_client/dialogs/tdlib/normalizers/bootstrap_normalizer.py.

Errors

Error Type/Code When happens Notes
stickers service is not configured string Service-side validation or branch guard Returned as the error field of the error event.
TDLib / transport error string Raw API call fails or TDLib raises in the transport wrapper Forwarded from TdlibBaseClient.tg_call() or returned by the service.

Flow

  • TDLibListChatsConsumer.receive_json() forwards the WebSocket action into publish_command().
  • AccountOwnerWorker receives the command envelope and invokes dispatch_command_payload().
  • Registry handler handle_media_commands processes get_stickers_pack.
  • Service layer executes backend/tg_client/dialogs/tdlib/services/bootstrap_service.py::get_stickers_pack.
  • Raw TDLib wrapper(s): backend/tg_client/dialogs/tdlib/api/chats.py, backend/tg_client/dialogs/tdlib/api/profiles.py.
  • Result normalization / shaping: backend/tg_client/dialogs/tdlib/normalizers/bootstrap_normalizer.py.
  • Final payload is emitted through ctx.send() / ctx.send_response() -> send_ws() -> live event publisher.
  • Sibling commands in this handler group: download_file, get_custom_emoji_media, get_recent_stickers, get_prem_path.