tg_client WebSocket Docs: Domain Core Reference

Workflow (загальний)

1. Frontend підключає control socket до /ws/chats/ і отримує connected.ws_connection_id.
2. Frontend надсилає {"action":"open_client","userbot_ids":[...],"client_request_id":"unique-id"} у control socket і чекає відповідний open_client_ready.
3. Bootstrap/sync списку можна запитувати відразу після ack. Паралельно frontend підключає media socket до /ws/chats/media/ і прив'язує через open_media_stream; media-команди починає після media_stream_ready.
4. Надсилає команди (open_dialog, send_message, ...).
5. Consumer публікує owner command у NATS JetStream subject відповідного shard.
6. Shard owner отримує команду, виконує TDLib методи і публікує відповіді в NATS live subject акаунта.
7. Live updates, command responses і media events публікуються в TG_EVT та transient Core NATS subjects rt.*.tg.evt.acc.{userbot_id}.>.
8. Control socket повертає команди та важливі Telegram updates; media socket повертає media_pending, дозволений media_progress і media_ready.

Формат запиту: завжди містить action + зазвичай userbot_id.

Обмеження авторизації Telegram

Control WS надсилає telegram_client_status зі stage:"authorization_rate_limited" та error_code:"AUTHORIZATION_RATE_LIMITED". Статус стосується одного userbot_id; інші акаунти продовжують працювати.

{
  "type": "telegram_client_status",
  "userbot_id": 93,
  "stage": "authorization_rate_limited",
  "status": "error",
  "error_code": "AUTHORIZATION_RATE_LIMITED",
  "is_rate_limited": true,
  "terminal": true,
  "retryable": true,
  "retry_after_ms": 70200000,
  "retry_at_ms": 1792661400000
}

retry_at_ms — абсолютний Unix timestamp у мілісекундах; retry_after_ms — залишок на момент формування події. Frontend показує повідомлення про тимчасове обмеження й час наступної спроби, завершує pending-стани та зупиняє startup/history/media retry-таймери цього акаунта до дедлайну. Наявний кеш можна показувати з позначкою недоступності актуального стану.

Кожна відхилена WS-команда також отримує <command>_error зі своїми command_id, binding_generation і result.code:"AUTHORIZATION_RATE_LIMITED". У result передаються terminal, retryable, retry_after_ms і retry_at_ms. terminal:true завершує цей запит, а не видаляє акаунт і не означає logout.

Після дедлайну дозволена одна нова спроба запуску. Для відхиленої mutation new_command_id_required:true означає нову явну дію користувача з новим ID; автоматично повторно відправляти повідомлення не можна. Повторна доставка старого ID відтворює збережену відмову. Якщо Telegram не надав дедлайн, retryable:false забороняє автоматичний retry; потрібна явна авторизація. Успішна явна авторизація очищає попереднє обмеження; новіше обмеження, отримане під час завершення цієї авторизації, залишається чинним.

Два WebSocket для frontend

Control: wss://HOST/ws/chats/. Через нього frontend надсилає всі команди: open_client, get_chats, open_dialog, send/edit message, read state та download_file. Відповіді команд і важливі Telegram updates також приходять сюди.

Media: wss://HOST/ws/chats/media/. Він read-only і приймає тільки прив'язку open_media_stream. Через нього приходять media_pending, media_ready, custom emoji media без зміни payload, progress великих/manual downloads та прогрес вихідних Telegram uploads. Progress для preview, avatar і emoji не надсилається.

Під час відправлення медіа TDLib-події updateFile перетворюються на media_progress з kind:"outgoing_upload", direction:"upload", stage:"telegram_upload", uploaded_bytes, total_bytes і progress від 0 до 1. Для зіставлення доступні file_id, chat_id, тимчасовий msg_id, клієнтський sending_id та media_type. Фінальна progress-подія має media_status:"completed" і progress:1.0; остаточний результат відправлення, як і раніше, визначається через updateMessageSendSucceeded/updateMessageSendFailed.

{
  "type": "media_progress",
  "result": {
    "kind": "outgoing_upload",
    "direction": "upload",
    "stage": "telegram_upload",
    "media_status": "progress",
    "file_id": 2306,
    "chat_id": "8131729113",
    "msg_id": 5891948544,
    "sending_id": 42,
    "uploaded_bytes": 65536,
    "total_bytes": 155084,
    "progress": 0.4226
  }
}

// 1. Відкрити control WS і дочекатися connected
const control = new WebSocket("wss://HOST/ws/chats/");

control.addEventListener("message", ({ data }) => {
  const event = JSON.parse(data);
  if (event.type !== "connected") return;

  // 2. Спочатку активувати account stream у control WS
  control.send(JSON.stringify({ action: "open_client", userbot_ids: [184] }));

  const onControlReady = ({ data: controlData }) => {
    const controlEvent = JSON.parse(controlData);
    if (controlEvent.type !== "open_client_ready") return;
    control.removeEventListener("message", onControlReady);

    // 3. Відкрити media WS і зв'язати його з control ws_connection_id
    const media = new WebSocket("wss://HOST/ws/chats/media/");
    media.addEventListener("open", () => media.send(JSON.stringify({
      action: "open_media_stream",
      control_ws_connection_id: event.ws_connection_id,
      userbot_ids: [184]
    })));
    media.addEventListener("message", ({ data: mediaData }) => {
      const mediaEvent = JSON.parse(mediaData);
      if (mediaEvent.type !== "media_stream_ready") return;
      // 4. Тепер можна надсилати download_file; get_chats/sync не чекають media WS
    });
  };
  control.addEventListener("message", onControlReady);
});

Вибрані акаунти визначає frontend. Backend не відстежує перемикання акаунта через polling. Під час переходу, наприклад, з 183 на 184 повторно надішліть open_media_stream у вже відкритий media socket. Новий список userbot_ids атомарно замінює попередні NATS-підписки:

media.send(JSON.stringify({
  action: "open_media_stream",
  control_ws_connection_id: controlWsConnectionId,
  userbot_ids: [184]
}));

// Застосовувати media events для 184 після media_stream_ready з userbot_ids: [184].

Backend перевіряє, що кожен запитаний userbot_id активний у вказаному control socket. Якщо перевірка не проходить, підписки не змінюються і frontend отримує error. Події попереднього акаунта, які вже були в outbound-черзі, після успішного перемикання відкидаються.

Після reconnect control socket отримує новий ws_connection_id, тому media socket також треба перепідключити і повторити open_media_stream. Якщо frontend відкриває інший чат, backend змінює dialog_token, скасовує попередній прогрів і не віддає media events старого діалогу.

Події між live_subscription_ready і media_stream_ready тимчасово буферизуються в Redis: максимум 256 подій на control connection, TTL 120 секунд. media_stream_ready надсилається одразу після перевірки control socket та готовності NATS subscriptions; replay буфера виконується фоном і не блокує старт frontend-команд. Ready payload містить ready_after_ms та timings_ms.control_validation/nats_subscriptions для діагностики. Це не довготривала історія: frontend має перепідключити media socket у межах TTL.

Media outbound має обмежену чергу й rate limit. Налаштування: TG_MEDIA_WS_BYTES_PER_SECOND (типово 524288), TG_MEDIA_WS_EVENTS_PER_SECOND (типово 50), TG_MEDIA_WS_QUEUE_MAX (типово 512). Коли черга переповнена, проміжний media_progress може бути відкинутий; media_ready не відкидається.

Результат admission завантажень

command_received підтверджує приймання команди owner, але не постановку файлів у чергу. Відповідь download_files надсилається після перевірки кешу та атомарного admission. accepted рахує лише queued, duplicate та ready. duplicate означає приєднання до наявного job, ready — ресурс із кешу; фактичний URL надходить окремим media_ready, який може випередити command reply.

{"type":"download_files","result":{
  "count":2,"accepted":1,
  "outcomes":[
    {"index":1,"file_id":101,"remote_id":"ref-a","status":"queued","retryable":false},
    {"index":2,"file_id":102,"remote_id":"ref-b","status":"queue_full","retryable":true,"retry_after_ms":1000}
  ],
  "rejected":[{"index":2,"file_id":102,"remote_id":"ref-b","status":"queue_full",
    "retryable":true,"retry_after_ms":1000,"error":"Media admission failed: queue_full"}]
}}

index — позиція у вихідному files[], починаючи з 1; rejected також містить validation errors. Для одного файлу відмова admission повертає download_file_error з file identity, result.status і result.retryable. Queue-full response не означає початок download: frontend знімає pending і повторює лише відхилені retryable файли після retry_after_ms із jitter, якщо account/WS/dialog scope ще чинний. Не повторювати весь batch або вже accepted елементи. Таймери повтору скасовувати при відписці чи зміні діалогу.

Результат команди завжди адресований початковому control WS і його binding generation. Disconnect не перетворює відповідь на account broadcast і не передає її іншому пристрою.

Завантаження аватарки

Окремий action не потрібний. Використовуйте download_file, але не прив'язуйте аватарку до повідомлення і не передавайте msg_id:0. Для user avatar передавайте user_id; для group/channel avatar — chat_id. Поле file_id із відповідного profile_photo є основним способом резолву, а remote_id — перевіркою identity/fallback.

{"action":"download_file","userbot_id":184,"source":"profile","user_id":"775560683","file_id":4321,"remote_id":"AQAD...","kind":"profile_photo"}
{"action":"download_file","userbot_id":184,"source":"chat_list_avatar","chat_id":"-1001234567890","file_id":5432,"remote_id":"AQAD...","kind":"chat_list_avatar"}

profile_photo тепер містить file_id як на верхньому рівні, так і в sizes[].file_id. Для потрібної якості беріть file_id і remote_id з одного елемента sizes[].

У sender payload також доступні пари avatar_file_id + avatar_remote_id і avatar_big_file_id + avatar_big_remote_id. Для user-sender у parsed повідомленнях open_dialog додатково повертаються has_active_stories і story_ids[]. Якщо стан історій тимчасово не вдалося визначити, has_active_stories=null; порожній підтверджений список повертається як false і []. Якщо старий/cached payload ще не має file_id, backend робить exact lookup через getUser, getUserFullInfo та останні getUserProfilePhotos. Це fallback; frontend усе одно має передавати file_id, коли він присутній.

Batch аватарок

Один download_file/download_files кадр може містити кілька незалежних owners. Кореневі chat_id/user_id не потрібні: кожен елемент files[] має власний chat_id або user_id, а також парні file_id + remote_id. Результати зберігають batch_index.

{"action":"download_file","userbot_id":184,"source":"profile","files":[{"user_id":"7520762986","file_id":4321,"remote_id":"AQAD...","kind":"profile_photo"},{"chat_id":"-1001234567890","file_id":5432,"remote_id":"AgAC...","kind":"chat_list_avatar"}]}

remote_id є opaque TDLib identifier: frontend не повинен визначати тип файлу лише за префіксом AQAD/AgAC. Backend не переписує префікс, але для get_chats гарантує нормалізований profile_photo.sizes[] з малим розміром, якщо Telegram надав avatar identity.

Live update: typing indicator

updateChatAction з action.@type = chatActionTyping містить збагачений sender_id: first_name, last_name, username, display_name. Також доступні sender, actor, sender_name, sender_display_name і sender_user_id.

{"type":"updateChatAction","chat_id":-100123,"action":{"@type":"chatActionTyping"},"sender_id":{"@type":"messageSenderUser","user_id":456,"first_name":"Іван","last_name":"Петренко","username":"ivan","display_name":"Іван Петренко"},"sender_display_name":"Іван Петренко"}

Live update: message interactions

updateMessageInteractionInfo містить chat_id, message_id і interaction_info. Реакції та їхні автори доступні лише як interaction_info.reactions і interaction_info.reaction_senders[], якщо подія містить реакції; масив авторів може бути порожнім. Для повного списку використовуйте get_message_reaction_senders; у message reactions можливість його отримати позначена canGetAddedReactions.

Це часткове оновлення наявного повідомлення за ключем (userbot_id, chat_id, message_id). Воно не містить content, message, sender, forwardInfo, preview чи chat_meta. Не замінюйте ним весь message object і не запускайте завантаження media. Повідомлення, якого немає у локальній історії, можна пропустити: його актуальний стан прийде з open_dialog.

interaction_info замінює попередні лічильники та реакції; значення null явно очищує цей стан. Кореневі aliases payload.reactions і payload.reaction_senders у цій події видалено: frontend має читати вкладені поля. Окремий updateMessageReactions передає ідентифікатори, reactions і reaction_senders у корені payload, оскільки не має interaction_info. Доставка interaction наразі лишається на рівні підписки на акаунт, тому перевіряйте акаунт і повідомлення перед застосуванням.

{"type":"chat_update","userbot_id":4,"payload":{"type":"updateMessageInteractionInfo","userbot_id":4,"chat_id":-100123,"message_id":555,"interaction_info":{"view_count":12,"forward_count":2,"reactions":{"canSeeList":false,"canGetAddedReactions":false,"results":[{"reaction":{"type":"emoji","emoticon":"👍"},"count":3,"chosenOrder":null}]},"reaction_senders":[]}}}

Client Session

Приклади запитів

{
  "action": "open_client",
  "userbot_ids": [1,2,3]
}

{"action":"get_active_sessions","userbot_id":1}

{"action":"terminate_session","userbot_id":1,"session_id":987654321}

{"action":"set_session_settings","userbot_id":1,"session_id":987654321,"can_accept_calls":false,"can_accept_secret_chats":true}

{"action":"terminate_all_other_sessions","userbot_id":1}

Channel Commands

Native chat-list state

Прямий контракт tdlib_chat_list_v3: compact bootstrap, cursor pages, entity replace/shallow merge, account-wide revision і replay. Старий enriched snapshot, JSON Patch і get_chats_end видалені.

Live chat_list_update містить changes[] із generation/base_revision/revision; застосовувати той самий reducer, що й для replay. Native text/caption/entities передаються без обрізання й форматування; скорочення видимого preview виконує frontend. Inline base64 не передається.

ТЗ frontend: повний контракт, приклади, гонки, pagination і rollout.

Dialog Commands

Приклади запитів

{"action":"open_dialog","userbot_id":1,"chat_id":"123","from_message_id":"0"}

Контракт open_dialog, 2026-10-14: повідомлення надходять одразу в open_dialog.messages[], без вкладеного chat_info. Після всіх сторінок поточного запиту backend надсилає один dialog_chat_info з останнім доступним authoritative контекстом (або cached контекстом, якщо authoritative metadata немає). Його result — сам об'єкт метаданих, без додаткової обгортки chat_info; завжди містить chat_id, а для topic — message_thread_id. Поля dialog_access, access, permissions та last_message вилучені. Окрема подія dialog_access для open_dialog більше не надсилається.

Frontend застосовує повідомлення до надходження метаданих. Для dialog_chat_info потрібно перевіряти account, ws_connection_id, binding_generation і dialog_token; подія доповнює header поточного діалогу та не замінює історію. Не трактуйте відсутність access як заборону або дозвіл: використовуйте стан прав із chat-list/profiles updates. pagination_setup залишається завершенням порції history. Порожній діалог надсилає dialog_empty лише з chat_id і optional message_thread_id, потім метадані. При помилці history або перерваному запиті метадані можуть не надійти. Метадані та права open_comments залишаються в його поточному потоці.

Єдиний носій pagination: для open_dialog та open_comments читайте unread_message_ids, next_older_id/next_newer_id, has_older, older_state/newer_state і boundary flags лише з pagination_setup.result. Тут також повертаються нормалізовані параметри запиту from_message_id, offset, limit та, якщо задані, center_message_id, window_before, window_after. Це echo параметрів запиту, а не фактичного native query: centered window може змінювати limit/offset під час читання. Для topic є message_thread_id. Застосовуйте setup лише до того самого account, connection, binding, dialog token і command_id. Кешована preview-сторінка не встановлює курсори; setup формується з authoritative сторінки, зокрема порожньої. При помилці або скасуванні завершення може не надійти. dialog_end залишається лише сповіщенням про підтверджений EOF.

history_method, tdlib_result_type, tdlib_total_count, source_message_count, filtered_message_count, parsed_message_count та custom_emoji_index_hits вилучені з payload сторінки. Діагностика доступна в логах backend; opt-in include_raw_history залишається окремим діагностичним потоком. count дорівнює кількості повідомлень поточної сторінки; message_is_read залишається в кожному повідомленні.

Для GIF (content[].type = messageAnimation) об'єкт sizes містить width/height оригінальної анімації в пікселях та size повного файлу в байтах, як у відео. Поля додаються, якщо їх надав TDLib. minithumbnail.width/height описують лише мале preview.

{"type":"chat_update","userbot_id":1,"payload":{"type":"dialog_chat_info","result":{"chat_id":123,"id":123,"title":"Приклад","sign_messages":false,"show_message_sender":false},"ws_connection_id":"ws-1","dialog_token":"dialog-1","binding_generation":"generation-1","command_id":"open-1"}}

{"action":"get_message_viewers","userbot_id":183,"chat_id":"-1001433999220","message_id":2258139873280}

{"action":"get_message_read_date","userbot_id":183,"chat_id":"7610536538","message_id":2258139873280}

{"action":"open_dialog","userbot_id":1,"chat_id":"123","from_message_id":"987654321","limit":50,"offset":-50}

{"action":"open_dialog","userbot_id":1,"chat_id":"123","center_message_id":"987654321","window_before":20,"window_after":20}

{"action":"open_dialog","userbot_id":1,"chat_id":"123","message_thread_id":"456","limit":30,"offset":0}

{"action":"get_forum_topics","userbot_id":1,"chat_id":"-1001234567890"}

{"action":"create_forum_topic","userbot_id":1,"chat_id":"-1001234567890","name":"Новини","icon_color":7322096}

{"action":"edit_forum_topic","userbot_id":1,"chat_id":"-1001234567890","message_thread_id":42,"name":"Оновлена назва"}

{"action":"delete_forum_topic","userbot_id":1,"chat_id":"-1001234567890","message_thread_id":42}

{"action":"close_forum_topic","userbot_id":1,"chat_id":"-1001234567890","message_thread_id":42}

{"action":"open_forum_topic","userbot_id":1,"chat_id":"-1001234567890","forum_topic_id":42}

{"action":"pin_forum_topic","userbot_id":1,"chat_id":"-1001234567890","message_thread_id":42}

{"action":"unpin_forum_topic","userbot_id":1,"chat_id":"-1001234567890","message_thread_id":42}

{"action":"open_comments","userbot_id":1,"comments_meta":{"discussion_chat_id":"-100999000777","message_thread_id":"9001"},"limit":50}

Comments належать native messageTopicThread з message_thread_id; це окремий тип від messageTopicForum.forum_topic_id. У open_comments та pagination_setup використовуйте message_thread_id. dialog_empty також містить chat_id і message_thread_id; has_comments=null означає, що загальний count невідомий, а не нуль. Коротка чи відфільтрована сторінка сама собою не доводить кінець гілки.

{"action":"open_comments","userbot_id":1,"discussion_chat_id":"-100999000777","message_thread_id":"9001","center_message_id":"987654321","window_before":20,"window_after":20}

{"action":"search_messages_in_chat","userbot_id":1,"chat_id":"123","query":"при","limit":30}

{"action":"search_messages_in_chat","userbot_id":183,"chat_id":"-1001433999220","sender_id":7610536538,"limit":50}

{"action":"search_messages_in_chat","userbot_id":183,"chat_id":"-1001433999220","sender_id":"-1009876543210","sender_type":"chat","limit":50}

{"action":"search_messages_in_chat","userbot_id":1,"chat_id":"123","query":"при","from_message_id":456,"offset":-1,"limit":30}

{"action":"search_messages_in_chat","userbot_id":1,"chat_id":"123","query":"","filter":"searchMessagesFilterPhotoAndVideo","limit":30}

{"action":"search_messages_in_chat","userbot_id":1,"chat_id":"123","filter":"searchMessagesFilterDocument","limit":30}

{"action":"search_messages_in_chat","userbot_id":1,"chat_id":"123","filter":"searchMessagesFilterUrl","limit":30}

{"action":"search_messages_in_chat","userbot_id":1,"chat_id":"123","filter":"searchMessagesFilterVoiceAndVideoNote","limit":30}

{"action":"search_messages_in_chat","userbot_id":1,"chat_id":"123","query":"звіт","date_from":"2026-08-01","date_to":"2026-08-31","limit":30}

{"action":"search_messages_in_chat","userbot_id":1,"search_mode":"saved_source_chats"}

{"action":"search_messages_in_chat","userbot_id":1,"saved_sources_only":true,"source_chat_id":"-1001234567890","limit":50}

{"action":"search_messages_in_chat","userbot_id":1,"search_mode":"saved_source_messages","saved_messages_topic_id":"777","source_chat_id":"-1001234567890","limit":50}

{"action":"search_messages_global","userbot_id":1,"query":"при","limit":30}

{"action":"search_messages_global","userbot_id":1,"filter":"searchMessagesFilterUnreadMention","limit":30}

{"action":"get_chat_recent_actions","userbot_id":1,"chat_id":"-1001234567890","limit":50}

{"action":"get_chat_recent_actions","userbot_id":1,"chat_id":"-1001234567890","from_event_id":"987654321","limit":50}

query необов'язковий: для вкладок медіа/файлів/посилань/голосових можна передавати порожній рядок.

Вкладка Недавні дії не є searchMessagesFilter*. Для неї використовуйте окрему команду get_chat_recent_actions (TDLib getChatEventLog).

Search Filters

Filter Aliases

Бекенд також приймає короткі значення: media, files, links, voice, photo, video, document, url тощо.

Вкладка Групи не є окремим TDLib searchMessagesFilter*; її роблять на фронті групуванням результатів (наприклад, за album_id або датою).

comments_meta у message payload: discussion_chat_id — linked discussion chat, message_thread_id — thread поста, comment_count — кількість коментарів. comments_enabled=true повертається лише коли TDLib підтвердив thread саме цього поста; сама наявність linked discussion group не відкриває коментарі. Ознаки comments_enabled/comments_closed відрізняють доступні порожні коментарі від закритих, has_comments показує наявність хоча б одного коментаря, а can_write_comments — можливість поточного акаунта писати.

Notification Settings

Notification actions працюють із server-side TDLib settings. Часткові set_* payload-и спочатку об'єднуються з поточними settings, тому невказані поля не скидаються.

{"action":"mute_chat","userbot_id":183,"chat_id":"-100123","mute_for":"8h"}
{"action":"set_chat_notification_settings","userbot_id":183,"chat_id":"-100123","show_preview":false,"use_default_show_preview":false,"sound_id":0,"use_default_sound":false}
{"action":"set_scope_notification_settings","userbot_id":183,"scope":"groups","mute_for":0,"show_preview":true}
{"action":"get_forum_topic_notification_settings","userbot_id":183,"chat_id":"-100123","message_thread_id":"41943040"}
{"action":"set_forum_topic_notification_settings","userbot_id":183,"chat_id":"-100123","message_thread_id":"41943040","mute_for":"3d","use_default_mute_for":false}
{"action":"mute_forum_topic","userbot_id":183,"chat_id":"-100123","message_thread_id":"41943040","mute_for":"8h"}
{"action":"unmute_forum_topic","userbot_id":183,"chat_id":"-100123","message_thread_id":"41943040"}
{"action":"set_reaction_notification_settings","userbot_id":183,"notification_settings":{"message_reaction_source":"contacts","story_reaction_source":"none","sound_id":0,"show_preview":true}}
{"action":"get_saved_notification_sounds","userbot_id":183}
{"action":"configure_notification_api","userbot_id":183,"notification_group_count_max":25,"notification_group_size_max":10}
{"action":"remove_notification","userbot_id":183,"notification_group_id":17,"notification_id":401}
{"action":"remove_notification_group","userbot_id":183,"notification_group_id":17,"max_notification_id":401}

Chat settings підтримують усі поля TDLib chatNotificationSettings: use_default_mute_for, mute_for, use_default_sound, sound_id, use_default_show_preview, show_preview, story-аналоги, disable_pinned_message_notifications та disable_mention_notifications разом з їхніми use_default_*.

Scope settings підтримують mute_for, sound_id, show_preview, use_default_mute_stories, mute_stories, story_sound_id, show_story_poster, disable_pinned_message_notifications, disable_mention_notifications.

Поля badge counter зі скриншота (увімкнено, рахувати чати чи повідомлення, включати групи/канали) є локальною UI/OS preference і не синхронізуються TDLib як account notification settings. Для розрахунку badge frontend використовує updateUnreadChatCount та updateUnreadMessageCount, які backend передає.

Backend також передає офіційні updates: updateChatNotificationSettings, updateScopeNotificationSettings, updateReactionNotificationSettings, updateSavedNotificationSounds, updateActiveNotifications, updateNotificationGroup, updateNotification і updateHavePendingNotifications.

Active Notification API за замовчуванням TDLib вимкнена. Спочатку викличте configure_notification_api з count > 0. Після цього updateActiveNotifications є початковим snapshot, а наступні зміни приходять через updateNotificationGroup/updateNotification. Actions remove_notification* треба викликати лише після явного видалення notification користувачем; це не mute і не read-state.

Push delivery через APNs/FCM/Web Push не вмикається цим action: registerDevice, getPushReceiverId і processPushNotification потребують окремого provider-specific device-token flow. Цей backend-флоу охоплює Telegram notification settings та active notifications у вже активному TDLib runtime.

Message Commands

Приклади запитів

{"action":"send_message","userbot_id":1,"chat_id":"123456","text":"Привіт","entities":[]}

{"action":"get_available_senders","userbot_id":1,"chat_id":"-1001234567890"}

{"action":"send_message","userbot_id":1,"chat_id":"-1001234567890","text":"Публікація","send_as_chat_id":"-1009876543210"}

{"action":"send_message","userbot_id":1,"chat_id":"222222","text":"Cross-chat reply","reply_to":{"replyToChatId":"111111","replyToMsgId":"555"}}

{"action":"create_poll","userbot_id":1,"chat_id":"123456","question":"Коли реліз?","poll_options":["Сьогодні","Завтра"],"poll_type":"regular","allows_multiple_answers":false}

{"action":"create_poll","userbot_id":1,"chat_id":"123456","question":"2 + 2?","poll_options":["3","4","5"],"poll_type":"quiz","correct_option_id":1,"explanation":"Правильна відповідь: 4"}

{"action":"set_poll_answer","userbot_id":1,"chat_id":"123456","message_id":"555","option_ids":[1]}

{"action":"get_poll_voters","userbot_id":1,"chat_id":"123456","message_id":"555"}

{"action":"stop_poll","userbot_id":1,"chat_id":"123456","message_id":"555"}

{"action":"send_message","userbot_id":1,"chat_id":"123456","text":"Album caption","entities":[{"offset":0,"length":5,"type":{"@type":"textEntityTypeBold"}}],"media_items":[{"type":"photo","key":"local-upload:OPAQUE_PHOTO_TOKEN","file_name":"one.jpg"},{"type":"video","key":"local-upload:OPAQUE_VIDEO_TOKEN","file_name":"two.mp4"}],"reply_to_message_id":"555","protect_content":true}

{"action":"send_comment","userbot_id":1,"comments_meta":{"discussion_chat_id":"-100999000777","message_thread_id":"9001"},"text":"це коментар"}

{"action":"send_comment","userbot_id":1,"discussion_chat_id":"-100999000777","message_thread_id":"9001","text":"reply в comments","reply_to_message_id":"555"}

{"action":"send_comment","userbot_id":1,"discussion_chat_id":"-100999000777","message_thread_id":"9001","text":"Файл у коментарях","entities":[{"offset":0,"length":4,"type":{"@type":"textEntityTypeBold"}}],"media":{"type":"document","key":"local-upload:OPAQUE_TOKEN","file_name":"report.pdf"},"protect_content":true}

{"type":"comments_access","userbot_id":1,"result":{"discussion_chat_id":"-100999000777","message_thread_id":"9001","comments_enabled":true,"comments_closed":false,"comment_count":0,"has_comments":false,"can_write_comments":true,"can_send_messages":true,"needs_join_to_send":false,"join_to_send_messages":false,"join_by_request":false}}

{"action":"edit_message","userbot_id":1,"chat_id":"123456","message_id":"555","text":"Оновлений текст"}

{"action":"edit_message","userbot_id":1,"chat_id":"123456","message_id":"555","text":"Оновлений caption","entities":[{"offset":0,"length":9,"type":{"@type":"textEntityTypeBold"}}],"media":{"type":"photo","key":"local-upload:OPAQUE_PHOTO_TOKEN","file_name":"new.jpg"}}

{"action":"delete_messages","userbot_id":1,"chat_id":"123456","message_ids":["555","556"],"revoke":true}

{"action":"mark_messages_as_read","userbot_id":183,"chat_id":"-1001433999220","message_id":"2258139873280"}

{"action":"mark_messages_as_read","userbot_id":183,"chat_id":"-1001433999220","message_ids":["2258139873280","2258139873281"],"message_thread_id":"41943040","force_read":true}

mark_messages_as_read повертає viewed_message_ids[], chat_id, message_thread_id, застосований force_read і актуальний read-state snapshot: unread_count, unread_mention_count, unread_reaction_count, is_marked_as_unread, last_read_inbox_message_id, last_read_outbox_message_id. Для topic додатково повертаються ті самі поля з префіксом topic_. Якщо TDLib прийняв viewMessages, але контрольний snapshot ще недоступний, команда залишається успішною з read_state_pending=true. За замовчуванням force_read=true, тому повідомлення буде прочитане навіть якщо чат зараз закритий. Значення false лише реєструє перегляд відповідно до поточного open-state TDLib.

Telegram зберігає read marker чату/топіка монотонно. Backend передає лише задані ID, але якщо прочитати пізніше повідомлення, Telegram може також вважати прочитаними попередні. Довільний набір “прочитане/непрочитане” з дірками Telegram не підтримує.

set_chat_read_state приймає chat_id і is_marked_as_unread або mark_as_read, опц. message_thread_id. Успішна відповідь містить прийняте значення is_marked_as_unread та read_state_pending: true, якщо контрольний native snapshot ще не підтверджує цей прапорець. Лічильники й read IDs беруться з контрольного snapshot; прийнятий прапорець не підміняє підтверджений стан у спільному кеші. Якщо контрольне читання завершується помилкою, зберігається error-відповідь, хоча mutation могла вже виконатися; це не дозвіл повторити її.

{"action":"reply_message","userbot_id":1,"chat_id":"123456","reply_to_message_id":"555","text":"Відповідь"}

{"action":"forward_message","userbot_id":1,"to_chat_ids":["111","222"],"from_chat_id":"123456","message_ids":["555"],"without_sender":true,"without_caption":true}

{"action":"forward_message","userbot_id":1,"to_chat_ids":["111"],"from_chat_id":"123456","message_ids":["555","556","557"]}

{"action":"pin_message","userbot_id":1,"chat_id":"123456","message_id":"555","disable_notification":false,"only_for_self":false}

{"action":"unpin_message","userbot_id":1,"chat_id":"123456","message_id":"555"}

{"action":"set_reaction","userbot_id":1,"chat_id":"123456","message_id":"555","reaction":{"type":"emoji","emoji":"🔥"},"is_big":false,"add_to_recent":true}

{"action":"set_reaction","userbot_id":1,"chat_id":"123456","message_id":"555","reaction":{"type":"custom_emoji","custom_emoji_id":"5393021912655030923"}}

{"action":"remove_reaction","userbot_id":1,"chat_id":"123456","message_id":"555","reaction":"👍"}

{"action":"remove_message_reaction","userbot_id":1,"chat_id":"123456","message_id":"555","custom_emoji_id":"5393021912655030923"}

{"action":"get_message_reaction_senders","userbot_id":1,"chat_id":"123456","message_id":"555","emoji":"🔥"}

{"action":"get_chat_reaction_settings","userbot_id":1,"chat_id":"-1001234567890"}

{"action":"enable_channel_reactions","userbot_id":1,"chat_id":"-1001234567890","max_reaction_count":11}

{"action":"set_chat_reaction_settings","userbot_id":1,"chat_id":"-1001234567890","mode":"some","reactions":[{"type":"emoji","emoji":"🔥"},{"type":"emoji","emoji":"👍"}],"max_reaction_count":4}

{"action":"set_chat_max_reaction_count","userbot_id":1,"chat_id":"-1001234567890","count":6}

{"action":"set_channel_paid_reactions","userbot_id":1,"chat_id":"-1001234567890","enabled":true}

{"action":"disable_chat_reactions","userbot_id":1,"chat_id":"-1001234567890"}

{"action":"get_callback_query_answer","userbot_id":1,"chat_id":"7104457942","message_id":"441450496","data":"Zm9sZGVyc19tYWlu"}

{"action":"get_callback_query_answer","userbot_id":1,"chat_id":"7104457942","message_id":"441450496","data":"folders_main","data_encoding":"utf-8"}

Media Commands

Приклади запитів

{"action":"download_file","userbot_id":1,"file_id":123456,"source":"dialogs","chat_id":"123456","msg_id":"555","message_thread_id":"456","extra":{"kind":"manual"}}

{"action":"download_file","userbot_id":183,"chat_id":"-1001964948658","remote_id":"EAAC...","source":"chat_background","queue_priority":"priority"}

Для source:"chat_background" поле chat_id обов'язкове. file_id можна не передавати: backend повторно читає актуальний chat.background через TDLib, знаходить wallpaper document у main session і безпечно обробляє ротацію remote_id. Generic getRemoteFile для цього source використовує fileTypeWallpaper.

{"action":"get_custom_emoji_media","userbot_id":1,"custom_emoji_ids":["5393021912655030923","5393021912655030924"],"request_id":"visible-stickers"}

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

{"action":"get_saved_gifs","userbot_id":1,"limit":100}

{"action":"search_gifs","userbot_id":1,"query":"cat","offset":"","limit":50}

{"action":"remove_saved_gif","userbot_id":1,"file_id":123456}

{"action":"delete_saved_gif","userbot_id":1,"gif":{"file_id":123456,"remote_id":"BQAD..."}}

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

GIF item payload

{"userbot_id":1,"type":"get_saved_gifs","result":{"items":[{"type":"animation","kind":"animation","file_id":123456,"remote_id":"BQAD...","thumbnail":{"kind":"animation_thumbnail","file_id":123457,"preview_for_file_id":123456},"download":{"source":"dialogs","kind":"animation","type":"animation","file_id":123456,"remote_id":"BQAD..."}}],"count":1,"limit":100}}

Для показу GIF використовуйте download_file з download item-а. Для preview можна завантажити thumbnail. Для видалення зі збережених передавайте file_id, remote_id або весь item у полі gif/animation.

Подія media_ready

media_ready — асинхронна WS-подія, яка приходить окремо від основної відповіді, коли бекенд вже підготував медіа і може віддати URL або asset.

{"userbot_id":1,"type":"media_ready","result":{...}}

Варіант 1: файл

{"userbot_id":1,"type":"media_ready","result":{"file_id":123456,"path":"https://...","kind":"avatar","remote_id":"AQAD...","chat_id":"-1001234567890","msg_id":"555"}}

Базові поля: file_id, path, kind. Додатково можуть приходити remote_id, chat_id, msg_id, user_id, message_thread_id, album_id, preview_index, preview_kind, preview_media_type, preview_type, preview_for_file_id, preview_for_file_format, preview_for_file_size, waveform, sticker_format, emoji, source.

Звичайні стікери: media_ready.result.kind=sticker; для picker-запиту зберігається sticker_id, а file_id/remote_id позначають ресурс поточного акаунта. format, file_format і sticker_format мають значення webp, tgs або webm; mime_type/content_type — відповідний MIME. Контракт однаковий для нового завантаження і cache hit. Frontend показує WebP як зображення, TGS через Lottie renderer, WebM як відео. Формат не визначайте за token URL: він не має файлового розширення. Якщо формат невідомий, backend повертає format=null. Preview/thumbnail стікера зберігає власний файловий payload; custom emoji має kind=custom_emoji та emoji_id.

Dialog scope завантажень: активний view і token встановлюються командами відкриття історії. Спільний ingress download_file/download_files фіксує наявний token акаунта з RAM gateway; його актуальність перевіряє canonical MediaDelivery на owner. Download-запити не створюють і не перемикають view. source=chat_list_preview та extra.kind=chat_list_preview проходять background command flow без dialog token; preview іншого чату зберігає відкритий діалог. Контракт frontend не змінюється.

Варіант 2: custom emoji

{"userbot_id":1,"type":"media_ready","result":{"emoji_id":"5393021912655030923","kind":"custom_emoji","file_id":987654,"path":"https://...","emoji_webm":"https://...","is_lottie":false,"source":"custom_emoji_batch","request_id":"composer-emoji-pack","batch_index":1,"batch_total":2}}

Для custom emoji приходять emoji_id, kind=custom_emoji і або path/emoji_json_url з is_lottie=true, або path/emoji_webm з is_lottie=false. Додатково можливі file_id, chat_id, msg_id, message_thread_id, source, request_id, batch_index, batch_total.

Порядок завантаження: медіа вантажиться тільки явною командою фронта. Для файлів спочатку перевіряється кеш/клауд, і тільки потім йде догрузка з TG. Поле path у media_ready — це URL на об'єкт у клауді; для public emoji/sticker bucket він може бути стабільним публічним URL, а для інших media — presigned URL.

Коли приходить:

• download_file — після ручного завантаження файлу;
• get_chats і get_recently_opened_chats — тільки для аватарок і preview;
• search_messages_in_chat і search_messages_global — тільки для аватарок і preview;
• open_dialog — для повного медіа та custom emoji;
• get_custom_emoji_media — для пакетного завантаження custom emoji по масиву id, зокрема для видимих елементів зі sticker pack;

User / Chat Profiles / Contacts

Приклади запитів

{"action":"search_user","userbot_id":1,"username":"@durov"}

{"action":"search_chats_global","userbot_id":1,"query":"openai","limit":20}

{"action":"create_private_chat","userbot_id":1,"user_id":777000,"force":false}

{"action":"create_supergroup_chat","userbot_id":1,"title":"Моя група","is_channel":false,"description":"Опис групи"}

{"action":"create_supergroup_chat","userbot_id":1,"title":"Мій канал","is_channel":true,"description":"Опис каналу"}

{"action":"open_dialog","userbot_id":1,"chat_id":"123456789","from_message_id":"0"}

{"action":"get_user","userbot_id":1,"user_id":"777000"}

{"action":"get_groups_in_common","userbot_id":1,"user_id":"777000","limit":20}

{"action":"get_groups_in_common","userbot_id":1,"user_id":"777000","offset_chat_id":"-1001234567890","limit":20}

{"action":"get_chat_profile","userbot_id":1,"chat_id":"-1001234567890"}

{"action":"set_name","userbot_id":1,"first_name":"Pavlo","last_name":"Petrenko"}

{"action":"set_name","userbot_id":1,"full_name":"Pavlo Petrenko"}

{"action":"set_bio","userbot_id":1,"bio":"Backend engineer"}

{"action":"set_bio","userbot_id":1,"bio":""}

{"action":"set_username","userbot_id":1,"username":"pavlo_dev"}

{"action":"set_username","userbot_id":1,"username":""}

{"action":"set_profile_photo","userbot_id":1,"photo":{"key":"local-upload:OPAQUE_PROFILE_TOKEN","file_name":"avatar.jpg"},"is_public":false}

{"action":"set_birthdate","userbot_id":1,"day":17,"month":5,"year":1998}

{"action":"set_birthdate","userbot_id":1,"day":17,"month":5,"year":0}

{"action":"set_birthdate","userbot_id":1,"birthdate":{"day":17,"month":5,"year":1998}}

{"action":"set_birthdate","userbot_id":1,"birthdate":null}

{"action":"set_chat_title","userbot_id":1,"chat_id":"-1001234567890","title":"Новий заголовок"}

{"action":"set_chat_description","userbot_id":1,"chat_id":"-1001234567890","description":"Новий опис"}

{"action":"set_chat_permissions","userbot_id":1,"chat_id":"-1001234567890","permissions":{"can_send_basic_messages":true,"can_send_photos":true,"can_send_videos":true,"can_send_polls":false,"can_add_link_previews":true,"can_invite_users":true}}

{"action":"toggle_supergroup_has_hidden_members","userbot_id":1,"chat_id":"-1001234567890","has_hidden_members":true}

{"action":"toggle_supergroup_has_hidden_members","userbot_id":1,"chat_id":"-1001234567890","has_hidden_members":false}

{"action":"add_chat_member_permission_exception","userbot_id":1,"chat_id":"-1001234567890","user_id":777000,"permissions":{"can_send_photos":false},"restricted_until_date":0}

{"action":"edit_chat_member_permission_exception","userbot_id":1,"chat_id":"-1001234567890","user_id":777000,"permissions":{"can_send_photos":true,"can_send_polls":false}}

{"action":"delete_chat_member_permission_exception","userbot_id":1,"chat_id":"-1001234567890","user_id":777000}

{"action":"check_chat_username","userbot_id":1,"chat_id":"-1001234567890","username":"my_channel"}

{"action":"set_supergroup_username","userbot_id":1,"chat_id":"-1001234567890","username":"my_channel"}

{"action":"set_supergroup_username","userbot_id":1,"chat_id":"-1001234567890","username":""}

{"action":"toggle_chat_has_protected_content","userbot_id":1,"chat_id":"-1001234567890","has_protected_content":true}

{"action":"set_chat_slow_mode_delay","userbot_id":1,"chat_id":"-1001234567890","slow_mode_delay":60}

{"action":"set_chat_slow_mode_delay","userbot_id":1,"chat_id":"-1001234567890","slow_mode_delay":0}

{"action":"set_chat_direct_messages_group","userbot_id":1,"chat_id":"-1001234567890","is_enabled":true,"paid_message_star_count":0}

{"action":"set_chat_direct_messages_group","userbot_id":1,"chat_id":"-1001234567890","is_enabled":true,"paid_message_star_count":100}

{"action":"set_chat_direct_messages_group","userbot_id":1,"chat_id":"-1001234567890","is_enabled":false,"paid_message_star_count":0}

{"action":"set_chat_discussion_group","userbot_id":1,"chat_id":"-1001234567890","discussion_chat_id":"-1009876543210"}

{"action":"set_chat_discussion_group","userbot_id":1,"chat_id":"-1001234567890","discussion_chat_id":0}

{"action":"get_suitable_discussion_chats","userbot_id":1}

{"action":"get_suitable_personal_chats","userbot_id":1}

{"action":"set_personal_chat","userbot_id":1,"chat_id":"-1001234567890"}

{"action":"hide_personal_chat","userbot_id":1}

{"action":"get_chat_members","userbot_id":1,"chat_id":"-1001234567890","limit":30,"offset":0,"filter":"recent"}

{"action":"get_chat_members","userbot_id":1,"chat_id":"-1001234567890","limit":30,"query":"andrey","filter":"members"}

{"action":"get_chat_members","userbot_id":1,"chat_id":"-1001234567890","limit":30,"offset":0,"filter":"admins"}

{"action":"get_chat_members","userbot_id":1,"chat_id":"-1001234567890","limit":30,"offset":0,"filter":"blocked"}

{"action":"import_contacts","userbot_id":1,"phone":"+380991112233","first_name":"Ivan","last_name":"Petrenko","vcard":"","contact_user_id":0}

{"action":"import_contacts","userbot_id":1,"phone":"+380991112233","first_name":"Ivan","last_name":""}

{"action":"block_user","userbot_id":1,"user_id":777000,"is_blocked":true}

{"action":"block_user","userbot_id":1,"user_id":777000,"is_blocked":false}

{"action":"unblock_user","userbot_id":1,"user_id":777000}

{"action":"get_blocked_users","userbot_id":1,"offset":0,"limit":50}

{"action":"get_privacy_setting","userbot_id":1,"setting":"last_seen"}

{"action":"get_privacy_settings","userbot_id":1,"settings":["phone_number","last_seen","groups_and_channels","calls","profile_photo","bio","gifts","birthdate","forwarded_messages","voice_messages","messages"]}

{"action":"set_privacy_setting","userbot_id":1,"setting":"last_seen","mode":"nobody","always_allow_user_ids":[777000,123456789],"never_allow_user_ids":[987654321]}

{"action":"set_privacy_setting","userbot_id":1,"setting":"groups_and_channels","mode":"contacts","allow_chat_ids":[-1001234567890]}

{"action":"set_privacy_setting","userbot_id":1,"setting":"messages","allow_new_chats_from_unknown_users":true}

{"action":"add_chat_member","userbot_id":1,"chat_id":"-1001234567890","user_id":777000,"forward_limit":0}

{"action":"add_chat_members","userbot_id":1,"chat_id":"-1001234567890","user_ids":[777000,123456789]}

У add_chat_member та add_chat_members перевіряйте result.failed_to_add_members. Порожній список — усіх запитаних користувачів додано; непорожній — повна або часткова відмова. Для зазначених ID можна запропонувати «Запросити посиланням», враховуючи native прапорці Premium. Не показуйте «додано» лише за назвою події. Верхньорівнева TDLib-помилка надходить як <action>_error.

{"type":"add_chat_members","result":{"@type":"failedToAddMembers","failed_to_add_members":[{"@type":"failedToAddMember","user_id":777000,"premium_would_allow_invite":false,"premium_required_to_send_messages":true}]}}

{"action":"remove_chat_member","userbot_id":1,"chat_id":"-1001234567890","user_id":777000,"revoke_messages":false}

{"action":"restore_chat_member","userbot_id":1,"chat_id":"-1001234567890","user_id":777000}

{"action":"add_chat_administrator","userbot_id":1,"chat_id":"-1001234567890","user_id":777000,"custom_title":"Модератор"}

{"action":"add_chat_administrator","userbot_id":1,"chat_id":"-1001234567890","user_id":777000,"rights":{"can_delete_messages":true,"can_invite_users":true,"can_manage_chat":true}}

{"action":"create_chat_member_tag","userbot_id":1,"chat_id":"-1001234567890","user_id":777000,"tag":"Модератор"}

{"action":"edit_chat_member_tag","userbot_id":1,"chat_id":"-1001234567890","user_id":777000,"tag":"Старший модератор"}

{"action":"delete_chat_member_tag","userbot_id":1,"chat_id":"-1001234567890","user_id":777000}

{"action":"remove_chat_administrator","userbot_id":1,"chat_id":"-1001234567890","user_id":777000}

{"action":"transfer_chat_ownership","userbot_id":1,"chat_id":"-1001234567890","user_id":777000,"password":"your_2fa_password"}

{"action":"get_password_state","userbot_id":1}

{"action":"request_2fa_password_recovery","userbot_id":1}

{"action":"check_password_recovery_code","userbot_id":1,"recovery_code":"12345"}

{"action":"recover_password","userbot_id":1,"recovery_code":"12345","new_password":"new_2fa_password","new_hint":"My hint"}

{"action":"verify_2fa_password","userbot_id":1,"password":"current_2fa_password"}

{"action":"change_2fa_password","userbot_id":1,"current_password":"current_2fa_password","new_password":"new_2fa_password","new_hint":"My hint"}

{"action":"change_2fa_password","userbot_id":1,"current_password":"current_2fa_password","new_password":"new_2fa_password","new_hint":"My hint","set_recovery_email_address":true,"new_recovery_email_address":"me@example.com"}

{"action":"disable_2fa_password","userbot_id":1,"current_password":"current_2fa_password"}

{"action":"change_2fa_recovery_email","userbot_id":1,"current_password":"current_2fa_password","new_recovery_email_address":"new@example.com"}

{"action":"get_transfer_ownership_state","userbot_id":1}

{"action":"toggle_supergroup_sign_messages","userbot_id":1,"chat_id":"-1001234567890","sign_messages":true}

{"action":"toggle_supergroup_sign_messages","userbot_id":1,"chat_id":"-1001234567890","sign_messages":true,"show_message_sender":true}

{"action":"toggle_supergroup_is_all_history_available","userbot_id":1,"chat_id":"-1001234567890","is_all_history_available":true}

{"action":"toggle_supergroup_is_forum","userbot_id":1,"chat_id":"-1001234567890","is_forum":true}

{"action":"toggle_supergroup_is_forum","userbot_id":1,"chat_id":"-1001234567890","is_forum":false}

{"action":"check_chat_invite_link","userbot_id":1,"invite_link":"https://t.me/+abc"}

{"action":"join_chat_by_invite_link","userbot_id":1,"invite_link":"https://t.me/+abc"}

{"action":"join_chat_by_invite_link","userbot_id":1,"link":"https://t.me/my_public_channel"}

{"action":"join_chat","userbot_id":183,"chat_id":"-1001661151013"}

{"action":"get_chat_invite_links","userbot_id":1,"chat_id":"-1001234567890","is_revoked":false,"limit":50}

{"action":"create_chat_invite_link","userbot_id":1,"chat_id":"-1001234567890","name":"Ads A","expiration_date":0,"member_limit":0,"creates_join_request":false}

{"action":"create_chat_subscription_invite_link","userbot_id":1,"chat_id":"-1001234567890","name":"Paid 30d","subscription_pricing":{"period":2592000,"star_count":100}}

{"action":"edit_chat_subscription_invite_link","userbot_id":1,"chat_id":"-1001234567890","invite_link":"https://t.me/+paid_abc","name":"Paid 30d (new name)"}

{"action":"edit_chat_invite_link","userbot_id":1,"chat_id":"-1001234567890","invite_link":"https://t.me/+abc","name":"Ads A v2","member_limit":100}

{"action":"revoke_chat_invite_link","userbot_id":1,"chat_id":"-1001234567890","invite_link":"https://t.me/+abc"}

{"action":"replace_primary_chat_invite_link","userbot_id":1,"chat_id":"-1001234567890"}

{"action":"delete_revoked_chat_invite_link","userbot_id":1,"chat_id":"-1001234567890","invite_link":"https://t.me/+abc"}

{"action":"delete_all_revoked_chat_invite_links","userbot_id":1,"chat_id":"-1001234567890","creator_user_id":777000}

{"action":"get_chat_join_requests","userbot_id":1,"chat_id":"-1001234567890","invite_link":"","query":"","limit":50}

{"action":"get_chat_invite_link_members","userbot_id":1,"chat_id":"-1001234567890","invite_link":"https://t.me/+abc","only_with_expired_subscription":false,"limit":50}

{"action":"process_chat_join_request","userbot_id":1,"chat_id":"-1001234567890","user_id":777000,"approve":true}

{"action":"process_chat_join_requests","userbot_id":1,"chat_id":"-1001234567890","invite_link":"","approve":true}

{"action":"process_chat_join_requests","userbot_id":1,"chat_id":"-1001234567890","invite_link":"","approve":false}

CRUD: персональні винятки permissions

Виняток зберігається Telegram як chatMemberStatusRestricted для конкретного user_id. Це не бан: is_member=true, користувач залишається учасником групи.

add використовує загальні права чату як основу; edit використовує поточні права винятку. Тому в permissions можна передавати лише поля, які треба змінити. delete встановлює chatMemberStatusMember і повертає стандартні права групи.

Підтримувані permissions

can_send_basic_messages, can_send_audios, can_send_documents, can_send_photos, can_send_videos, can_send_video_notes, can_send_voice_notes, can_send_polls, can_send_other_messages, can_add_link_previews, can_change_info, can_invite_users, can_pin_messages, can_create_topics.

Aliases: can_send_messages → can_send_basic_messages, can_add_web_page_previews → can_add_link_previews, can_manage_topics → can_create_topics. can_send_media_messages одночасно керує audio/document/photo/video/video-note/voice-note.

Строк дії

restricted_until_date — Unix timestamp у секундах; 0 означає безстроковий виняток. В edit відсутнє поле зберігає поточний строк.

Success payload

{"type":"edit_chat_member_permission_exception","result":{"@type":"ok","chat_id":"-1001234567890","user_id":777000,"operation":"edit","permissions":{"@type":"chatPermissions","can_send_basic_messages":true,"can_send_photos":false},"restricted_until_date":0,"status":{"@type":"chatMemberStatusRestricted","is_member":true}}}

Помилки

Подія має суфікс _error. Типові причини: відсутні chat_id/user_id/permissions, виняток для edit не існує, недостатньо права can_restrict_members, користувач є власником/адміністратором або Telegram відхилив зміну.

Profile Responses (скорочено)

Для blocked/banned учасників пошук автора блокування є optional enrichment: до 3 сторінок admin log по 100 events і до 8 унікальних actor lookups на запит. Admission нових optional calls припиняється через 2 секунди; поточний native call завершується за чинним transport timeout. Це не гарантія відповіді за 2 секунди.

Якщо enrichment неповний, успішний result містить blocked_by_lookup: complete:false, reason, pages, unresolved_count (кількість унікальних учасників із неповними metadata). Причини: page_budget, time_budget, actor_budget, native_error, history_end, cursor_stalled. Це не помилка завантаження учасників: збережіть rows, pagination і доступні actor IDs/blocked_at. Відсутній blocked_by означає невідомі metadata; не запускайте автоматичні retries списку заради enrichment. За повного enrichment додаткового marker немає.

{"blocked_by_lookup":{"complete":false,"reason":"page_budget","pages":3,"unresolved_count":1}}

Фільтри для get_chat_members: recent, members, admins, contacts, bots, mentions, restricted, banned. Також підтримуються alias-и blocked/blocked_users (мапляться на banned). Можна передавати й оригінальні TDLib типи.

Privacy aliases для setting: phone_number, last_seen, groups_and_channels, calls, profile_photo, bio, gifts, birthdate, forwarded_messages, saved_music, saved_messages, voice_messages, messages. Режими: all, contacts, nobody. Для user exceptions використовуйте allow_user_ids/restrict_user_ids або alias-и always_allow_user_ids/never_allow_user_ids.

Frontend: Profile Data Permissions

Для get_chat_profile фронт орієнтується на result.permissions. Якщо прапорець false, відповідну дію в UI треба блокувати або ховати.

У dialog_access поле permissions та верхньорівневі can_* — ефективні можливості поточного Telegram-акаунта. Поле chat_permissions — загальні дозволи звичайних учасників групи з TDLib chat.permissions; воно не описує права owner/admin і тому може містити false для власника чату. Topic actions доступні лише коли is_forum=true.

Додаткові поля для рішень UI

Важливо: у каналах/супергрупах permissions описують базові права учасника. Права адміна треба брати окремо зі статусу учасника (не з цього блоку).

Frontend: Chat With Topics (повний приклад + повний опис полів)

Це приклад get_chat_profile для супергрупи з топіками (supergroup.is_forum=true, view_as_topics=true). Нижче наведено payload без скорочень і повну розшифровку.

Розшифровка кореневих полів chat

Розшифровка permissions (повністю)

Розшифровка positions і chat_lists

Розшифровка notification_settings (повністю)

Розшифровка available_reactions і profile_photo

Розшифровка supergroup (повністю)

Розшифровка supergroup_full_info (повністю)

Розшифровка bot_commands

Preview закріпленого повідомлення

Для service message messagePinMessage нормалізований елемент content[], а в live update також сирий message.content, містить pinned_message_preview. Поле text — текст або caption цільового повідомлення; якщо їх немає, frontend використовує label та type (наприклад GIF/messageAnimation, Відео/messageVideo). Для сумісності поруч передаються плоскі поля pinned_message_text, pinned_message_type і pinned_message_label.

{
  "type": "messagePinMessage",
  "message_id": 5750390784,
  "pinned_message_preview": {
    "message_id": 5750390784,
    "type": "messageAnimation",
    "label": "GIF",
    "text": "Підпис GIF"
  },
  "pinned_message_type": "messageAnimation",
  "pinned_message_label": "GIF",
  "pinned_message_text": "Підпис GIF"
}

Read state повідомлення

Кожне звичайне повідомлення в open_dialog.messages[] має boolean message_is_read. Для вхідного повідомлення значення обчислюється через last_read_inbox_message_id: ID до read marker включно мають true, новіші — false. Для вихідного використовується last_read_outbox_message_id; pending/failed завжди мають false. У forum topic backend використовує topic-specific inbox marker.

Frontend: Channel Chat (is_channel=true, повний приклад + повний опис полів)

Це приклад get_chat_profile для каналу (type.is_channel=true, supergroup.is_channel=true). Нижче наведено повний payload і повну розшифровку для фронту.

Кореневі поля chat для channel (повністю)

permissions для channel (повністю)

supergroup для channel (повністю)

supergroup_full_info для channel (повністю)

Frontend: Basic Group Chat (chatTypeBasicGroup, повний приклад + повний опис полів)

Це приклад get_chat_profile для basic group (type.@type=chatTypeBasicGroup). Нижче повний payload та повна розшифровка.

Ключові поля basic group

permissions для basic group (повністю)

basic_group і basic_group_full_info (повністю)

Окремо: якщо поточний користувач адміністратор basic group

Важливо: для basic group роль користувача (member/admin/creator) визначається насамперед через basic_group.status. Прапорці permissions описують дозволи в чаті, але не замінюють role-based перевірку для адмінських екранів.

Telegram Stories

can_post_story викликає TDLib canPostStory і повертає canPostStoryResult* разом із can_post_story. get_chats_to_post_stories викликає getChatsToPostStories. Для власних stories передавайте Saved Messages chat ID. post_story повертає тимчасову story; остаточний результат приходить через updateStoryPostSucceeded / updateStoryPostFailed.

Усі відповіді мають тип, рівний action, або <action>_error. Ідентифікатор автора story передається як story_sender_chat_id; alias story_poster_chat_id теж підтримується. Для chat-list команд можна використовувати chat_id.

Stories у get_chats і get_chat_profile

Кожен get_chats.result.chat і кореневий payload get_chat_profile.result містить однакові поля has_active_stories, has_unread_active_stories та stories. stories.story_albums_supported є capability встановленої TDLib: true — album actions доступні; false — libtdjson.so не містить getChatStoryAlbums; null — capability ще не визначена або запит тимчасово не виконався. Викликайте stories.story_albums_action лише коли story_albums_supported=true.

{
  "has_active_stories": true,
  "has_unread_active_stories": true,
  "stories": {
    "load_state": "ready",
    "active_story_count": 2,
    "story_ids": [39, 42],
    "unread_story_ids": [42],
    "story_albums_supported": true,
    "has_story_albums": true,
    "story_album_count": 2,
    "story_album_ids": [3, 7],
    "story_albums_action": {"action":"get_chat_story_albums","chat_id":"775560683"},
    "max_read_story_id": 40,
    "can_be_archived": false,
    "stories": [{"@type":"storyInfo","story_id":39},{"@type":"storyInfo","story_id":42}],
    "view_action": {"action":"get_chat_active_stories","chat_id":"775560683"},
    "open_action": {"action":"get_story","story_sender_chat_id":"775560683","story_id":42}
  }
}

Для кліку на avatar ring фронт може виконати stories.view_action, отримати повні активні stories, а потім викликати open_story для фактично показаної story. stories.open_action одразу вказує на першу непрочитану story; якщо непрочитаних немає — на першу активну.

Request payload для кожного action

{"action":"get_story","userbot_id":183,"story_sender_chat_id":"775560683","story_id":42,"only_local":false}

{"action":"download_story","userbot_id":183,"story_sender_chat_id":"775560683","story_id":42}

{"action":"get_chat_active_stories","userbot_id":183,"chat_id":"775560683"}

{"action":"get_chat_archived_stories","userbot_id":183,"chat_id":"775560683","from_story_id":0,"limit":50}

{"action":"get_chat_posted_stories","userbot_id":183,"chat_id":"-1001234567890","from_story_id":0,"limit":50}

{"action":"get_chats_to_post_stories","userbot_id":183}

{"action":"can_post_story","userbot_id":183,"chat_id":"775560683"}

{"action":"post_story","userbot_id":183,"chat_id":"775560683","content":{"@type":"inputStoryContentPhoto","photo":{"@type":"inputFileId","id":6502},"added_sticker_file_ids":[]},"areas":null,"caption":{"@type":"formattedText","text":"Текст","entities":[]},"privacy_settings":{"@type":"storyPrivacySettingsEveryone"},"active_period":86400,"from_story_full_id":null,"is_posted_to_chat_page":false,"protect_content":false}

{"action":"post_story","userbot_id":183,"chat_id":"7610536538","content":{"@type":"inputStoryContentPhoto","photo":{"key":"local-upload:OPAQUE_STORY_TOKEN","file_name":"story.jpg"},"added_sticker_file_ids":[]},"caption":"Текст","privacy_settings":{"@type":"storyPrivacySettingsSelectedUsers","user_ids":[700372203]},"active_period":86400}

Для нового локального файлу спочатку викличте create_tg_media_upload_url, завантажте binary через отриманий upload URL, а в content.photo/content.video передайте саме повернений key. Не передавайте upload URL як original_path.

{"action":"edit_story","userbot_id":183,"story_sender_chat_id":"775560683","story_id":42,"content":null,"areas":null,"caption":"Оновлений текст"}

{"action":"delete_story","userbot_id":183,"story_sender_chat_id":"775560683","story_id":42}

{"action":"open_story","userbot_id":183,"story_sender_chat_id":"775560683","story_id":42}

{"action":"close_story","userbot_id":183,"story_sender_chat_id":"775560683","story_id":42}

{"action":"get_story_interactions","userbot_id":183,"story_id":42,"query":"","only_contacts":false,"prefer_forwards":false,"prefer_with_reaction":false,"offset":"","limit":50}

{"action":"get_story_interactions","userbot_id":183,"story_sender_chat_id":"-1001234567890","story_id":42,"reaction_type":null,"prefer_forwards":false,"offset":"","limit":50}

{"action":"set_story_privacy_settings","userbot_id":183,"story_id":42,"privacy_settings":{"@type":"storyPrivacySettingsContacts","except_user_ids":[]}}

{"action":"set_story_reaction","userbot_id":183,"story_sender_chat_id":"775560683","story_id":42,"reaction_type":{"@type":"reactionTypeEmoji","emoji":"❤"},"update_recent_reactions":true}

{"action":"set_story_reaction","userbot_id":183,"story_sender_chat_id":"775560683","story_id":42,"reaction_type":null}

{"action":"reply_to_story","userbot_id":183,"story_poster_chat_id":"775560683","story_id":42,"text":"Відповідь на story","entities":[]}

{"action":"reply_to_story","userbot_id":183,"story_poster_chat_id":"775560683","story_id":42,"caption":"Фото у відповідь","media":{"type":"photo","file_id":6502}}

{"action":"toggle_story_is_posted_to_chat_page","userbot_id":183,"story_sender_chat_id":"775560683","story_id":42,"is_posted_to_chat_page":true}

{"action":"set_chat_pinned_stories","userbot_id":183,"chat_id":"775560683","story_ids":[42,39]}

{"action":"pin_story","userbot_id":183,"chat_id":"775560683","story_id":42}

{"action":"unpin_story","userbot_id":183,"chat_id":"775560683","story_id":42}

{"action":"archive_chat_stories","userbot_id":183,"chat_id":"775560683"}

{"action":"unarchive_chat_stories","userbot_id":183,"chat_id":"775560683"}

{"action":"get_chat_story_albums","userbot_id":183,"chat_id":"775560683"}

{"action":"get_story_album_stories","userbot_id":183,"chat_id":"775560683","story_album_id":7,"offset":0,"limit":50}

{"action":"create_story_album","userbot_id":183,"chat_id":"775560683","name":"Подорожі","story_ids":[42,39]}

{"action":"edit_story_album","userbot_id":183,"chat_id":"775560683","story_album_id":7,"name":"Літо"}

{"action":"add_stories_to_story_album","userbot_id":183,"chat_id":"775560683","story_album_id":7,"story_ids":[45]}

{"action":"remove_stories_from_story_album","userbot_id":183,"chat_id":"775560683","story_album_id":7,"story_ids":[39]}

{"action":"reorder_story_album_stories","userbot_id":183,"chat_id":"775560683","story_album_id":7,"story_ids":[45,42]}

{"action":"reorder_story_albums","userbot_id":183,"chat_id":"775560683","story_album_ids":[7,3,1]}

{"action":"delete_story_album","userbot_id":183,"chat_id":"775560683","story_album_id":7}

Success і error events

{"type":"chat_update","userbot_id":183,"payload":{"type":"get_story","result":{"@type":"story","id":42,"story_sender_chat_id":775560683,"permissions":{},"media_files":[]}}}

{"type":"chat_update","userbot_id":183,"payload":{"type":"get_story_error","error":"Story not found"}}

{"type":"chat_update","userbot_id":183,"payload":{"type":"get_chat_story_albums_error","error":"Story albums aren't supported by the installed TDLib schema...","result":{"error_code":"tdlib_story_albums_unsupported","feature":"story_albums","required_tdlib_method":"getChatStoryAlbums","retryable":false}}}

Назва success event завжди дорівнює action. Назва помилки — <action>_error. Для reply_to_story це reply_to_story / reply_to_story_error; success result містить надіслане повідомлення та поля reply_to_story=true, story_poster_chat_id, story_id. Для списків TDLib може повернути менше елементів за limit; наступну сторінку запитуйте з from_story_id останньої story. Для interactions використовуйте тільки серверний next_offset як наступний offset.

Story content і privacy

Завантаження story media

get_story і download_story повертають media_files[]. download_story не створює другий media pipeline: frontend передає дозволені файли пакетно в наявний action:

{"action":"download_files","userbot_id":183,"source":"story","files":[{"file_id":6502,"remote_id":"...","chat_id":"775560683","kind":"story_media"}]}

Результати завантаження надходять у Media WebSocket як стандартні media_pending, media_progress, media_ready. Перед запитом перевіряйте permissions.can_download.

Permissions у story payload

Бекенд додає permissions: can_download, can_save, can_take_screenshot, can_forward, can_reply, can_edit, can_delete, can_set_privacy, can_toggle_profile_visibility, can_get_statistics, can_get_interactions, is_content_protected. Telegram пов'язує збереження і screenshot із can_be_forwarded; для публікації це контролює protect_content.

Control WebSocket також транслює live-події TDLib: updateStory, updateStoryDeleted, updateStoryPostSucceeded, updateStoryPostFailed, updateChatActiveStories, updateStoryListChatCount, updateStoryStealthMode. Події мають native TDLib payload; UI не повинен очікувати додаткових permissions / media_files. У updateChatActiveStories список розташований у active_stories.stories; avatar ring оновлюється за цим списком без повторного get_chats.

replyInfo для відповіді на story

"replyInfo": {
  "type": "story",
  "story_id": 2,
  "story_poster_chat_id": "700372203",
  "story_sender_chat_id": "700372203",
  "is_expired": false
}

is_expired=false означає, що story ще є в активному списку автора; true — story вже вийшла з активного списку. Для reply, старшого за 48 годин, backend детерміновано повертає true вже у першому open_dialog. null можливий лише для недавньої story, коли lightweight parsing ще не має кешованого стану; уточнення приходить у dialog_reply_meta.

Не надсилайте download_file, якщо permissions.can_download=false. Story media використовує той самий media/CDN WebSocket flow, що й повідомлення, тому окремого завантажувача і дублювання кешу немає.