tg_client WebSocket Docs: Domain Core Reference

← Назад до розділів | Оновлення

Знайдено секцій: 0

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.

Нові повідомлення, картки та API ботів (TDLib 1.8.70)

Контракт звірено з офіційною схемою td_api.tl, c8828d50. Локальний manifest: dialogs/tdlib/messaging_schema.json. Спільний каталог команд, полів, мінімальних версій і read/write-політики: dialogs/tdlib/messaging_contract.py. Перевірка: python scripts/verify_messaging_schema.py /path/to/td_api.tl.

Усі команди нижче приймають userbot_id та client_request_id. Успіх: {"type":"<action>","userbot_id":1,"result":{...}}. Помилка: <action>_error; зберігається та сама кореляція запиту. Команди виконуються через наявний owner scheduler; зміни і запити до бота проходять durable admission.

WS actionПоляTDLib / результат
get_messenger_capabilities—Версія нативної бібліотеки і прапорці albums, formatted_text, rich_messages, checklists, widgets. Паралельні запити об'єднуються; успіх кешується на native session, помилка — на 1 секунду перед наступною спробою. Скасування одного очікувача не запускає дубль поточного getOption(version).
get_full_rich_messagechat_id, message_idgetFullRichMessage → richMessage; викликати на вимогу, якщо is_full=false. Не завантажувати окремо для кожного повідомлення історії.
get_message_propertieschat_id, message_idgetMessageProperties → messageProperties. Перевірка can_add_tasks, can_mark_tasks_as_done, can_be_edited та інших прав.
parse_text_entitiestext, parse_modeparseTextEntities → formattedText. parse_mode: HTML, MarkdownV2 або нативний textParseModeHTML/textParseModeMarkdown.
get_text_entitiestextgetTextEntities → textEntities; URL, згадки, хештеги та інші автоматичні entities.
edit_message_checklistchat_id, message_id, checklist, опц. reply_markupeditMessageChecklist → message.
add_checklist_taskschat_id, message_id, tasks[]addChecklistTasks → ok. Елементи: inputChecklistTask з унікальними позитивними int32 id та formattedText text.
mark_checklist_tasks_as_donechat_id, message_id, marked_as_done_task_ids[], marked_as_not_done_task_ids[]markChecklistTasksAsDone → ok; один id не може бути в обох масивах. Підсумковий стан приходить через updateMessageContent.
get_widget_public_datachat_id, message_idgetWidgetPublicData → widgetPublicData (data, poll_period). Лише для видимих віджетів, які попросили watchPublicData; об'єднувати polling за widget_id та дотримуватися poll_period.
get_widget_query_answerchat_id, message_id, query_type, datagetWidgetQueryAnswer → widgetQueryAnswer. data — base64 від 1–64 UTF-8 байтів. Підтримано widgetQueryTypeData без wallet. Це взаємодія з ботом, тому команда не класифікується як read-only.
edit_message_widget_datachat_id, message_id, edit_public_data, public_data, edit_chat_data, chat_dataeditMessageWidgetData → ok; для ботів. Окремі edit_* прапорці відрізняють незмінене поле від очищення порожнім рядком.
edit_inline_message_widget_datainline_message_id, edit_public_data, public_data, edit_chat_data, chat_dataeditInlineMessageWidgetData → ok; для ботів.
edit_widget_datawidget_id, public_data, cache_timeeditWidgetData → ok; для ботів, спільний стан shared widget.
answer_widget_querywidget_query_id, dataanswerWidgetQuery → ok; для ботів. data — UTF-8 рядок до 1024 байтів.
delete_message_ephemeral_contentchat_id, message_iddeleteMessageEphemeralContent → ok; прибирає тимчасову відповідь бота.

Історія та нові картки

open_dialog, history і обидва пошуки зберігають чинний плоский DTO. Для структурованих карток і невідомих нових типів додано native_content: нативний MessageContent з повними вкладеними полями. Наприклад, messageRichMessage.message.blocks містить pageBlockSlideshow (карусель), pageBlockCollage, таблиці, списки, цитати й кнопки; messageChecklist.list — завдання, completed_by, completion_date і права; messageWidget — html, public_data, chat_data, widget_id, caption та can_send_queries.

Це саме поле також зберігає дані подарунків, giveaway, paid media та майбутніх типів, які старий DTO ще не вміє розкладати. Системні local paths і @extra прибираються спільним native serializer; IDs передаються рядками. Повний контент не дублюється у content[] для нових карток. Native live updates залишаються у форматі tdlib_updates_v1. Медіа карток завантажується чинним download_file за account/chat/message та remote.id.

Відправлення та форматування

send_message і send_comment приймають text як рядок або formattedText. Entities зберігають UTF-16 offset/length і параметри PreCode.language, DateTime.unix_time/formatting_type, MediaTimestamp.media_timestamp, TextUrl, MentionName та CustomEmoji. HTML/Markdown спочатку перетворюється через parse_text_entities; HTML напряму не виконується бекендом.

Для rich messages, чеклістів і віджетів використовуйте input_message_content з нативними inputMessageRichMessage, inputMessageChecklist, inputMessageWidget або inputMessageSharedWidget. Файли в rich blocks і Markdown/HTML media використовують той самий opaque local-upload: flow; прямі inputFileLocal/inputFileGenerated заборонені на будь-якій глибині. Вкладені дерева мають обмеження глибини та кількості вузлів.

edit_message також приймає inputMessageRichMessage у input_message_content і передає його в editMessageText. Caption віджетів змінюється звичайним edit_message з полем caption; HTML надісланого віджета незмінний за контрактом Telegram.

{"action":"send_message","userbot_id":1,"chat_id":"123","input_message_content":{
  "@type":"inputMessageChecklist","checklist":{"@type":"inputChecklist",
  "title":{"@type":"formattedText","text":"План","entities":[]},
  "tasks":[{"@type":"inputChecklistTask","id":1,"text":{"@type":"formattedText","text":"Перевірити контракт","entities":[]}}],
  "others_can_add_tasks":false,"others_can_mark_tasks_as_done":true}}}

Live API ботів і сумісність

Додано updateMessageEphemeralContent, updateNewWidgetQuery, updateNewInlineWidgetQuery та updateNewWidgetCopyQuery. Вони передаються без перетворення контенту і не записуються у кеш історії. Нові buttonStyle* та icon_custom_emoji_id зберігаються у reply_markup і rich button rows.

Widget API вимагає TDLib 1.8.70+. На старішій бібліотеці повертається звичний error event із result.code="TDLIB_UPGRADE_REQUIRED". Прапорці capabilities описують версію бібліотеки, не гарантують Premium, прав чату, bot-only доступу чи доступності функції на сервері Telegram. Остаточні обмеження застосовує TDLib/Telegram. Бібліотека та frontend автоматично не оновлюються цими бекенд-змінами.

Для майбутнього renderer віджетів дотримуватися офіційного widget profile: ізольоване виконання, відсутність мережевого доступу, квоти ресурсів, tap/background permissions. Бекенд передає HTML як дані; wallet/signing-запити наразі не підтримуються.

Онлайн акаунта та повний sendChatAction

Контракт звірено зі схемою TDLib 1.8.70: усі 15 конструкторів ChatAction, 4 MessageTopic та поля sendChatAction включені до manifest. get_messenger_capabilities оголошує online_status, chat_actions і chat_action_topics. Останній прапорець вимагає TDLib 1.8.70+.

Онлайн відкритого акаунта

open_client автоматично вмикає foreground presence для доданих акаунтів. Опційне is_online:false відкриває клієнт без онлайн-статусу, наприклад для фонової вкладки. Повторний open_client зі збереженим набором не скидає явно встановлений offline intent. За foreground підписками backend застосовує TDLib setOption("online", optionValueBoolean).

{"action":"open_client","userbot_id":184,"is_online":true}
{"action":"set_online","userbot_id":184,"client_request_id":"presence-1","is_online":false}
{"type":"set_online","userbot_id":184,"client_request_id":"presence-1",
 "result":{"@type":"ok","is_online":false,"requested_is_online":false}}

set_online приймає boolean is_online для акаунта, відкритого цим control WS. У result.is_online — сукупний стан: якщо інше вікно ще активне, він залишиться true навіть за requested_is_online:false. Помилка — set_online_error. Парсер, фоновий runtime та Media WS самі по собі не вмикають online; налаштування приватності Telegram залишаються чинними.

Frontend flow: передавати is_online за document visibility/focus; при поверненні у вкладку встановлювати true, у фоні — false. Backend поновлює foreground lease своїм WS heartbeat; при закритті або зміні акаунта видаляє саме прив’язку цього вікна. Owner перевіряє стан кожні 5 секунд. Закриття одного вікна не вимикає інше.

Обриви: після штатного WS disconnect або open_client з порожнім набором акаунтів прив’язка прибирається одразу; offline застосовується на наступній перевірці owner. Якщо gateway аварійно зупинився та heartbeat більше не поновлюється, lease спливає за 45 секунд від останнього поновлення, потім owner перевіряє стан протягом наступних 5 секунд.

При фізичній втраті мережі disconnect спочатку має бути виявлений ASGI-сервером: heartbeat gateway працює до виявлення обриву. У entrypoint за замовчуванням UVICORN_WS_PING_INTERVAL=60 і UVICORN_WS_PING_TIMEOUT=120; виявлення може зайняти близько 180 секунд, плюс цикл owner. Значення можуть бути перевизначені в оточенні. TTL 45 секунд не є гарантією виявлення мережевого обриву за 45 секунд. Приховування вкладки без закриття WS потребує frontend set_online(false).

WS send_chat_action → TDLib sendChatAction

Обов’язкові userbot_id і chat_id. WS-поле action є назвою команди, тому нативний sendChatAction.action передається окремим chat_action. Решта нативних параметрів: nullable topic_id і business_connection_id (за замовчуванням порожній рядок; використовується ботами). Результат — нативний ok; помилки — send_chat_action_error з тим самим client_request_id.

{"action":"send_chat_action","userbot_id":184,"chat_id":"12345","client_request_id":"typing-1",
 "topic_id":null,"business_connection_id":"","chat_action":{"@type":"chatActionTyping"}}
{"type":"send_chat_action","userbot_id":184,"client_request_id":"typing-1","result":{"@type":"ok"}}
ChatAction @typeДодаткові поляПризначення
chatActionTyping—Введення тексту.
chatActionRecordingVideo—Запис відео.
chatActionUploadingVideoprogress: int32, 0–100Надсилання відео.
chatActionRecordingVoiceNote—Запис голосового повідомлення.
chatActionUploadingVoiceNoteprogress: int32, 0–100Надсилання голосового повідомлення.
chatActionUploadingPhotoprogress: int32, 0–100Надсилання фото.
chatActionUploadingDocumentprogress: int32, 0–100Надсилання документа.
chatActionChoosingSticker—Вибір стікера.
chatActionChoosingLocation—Вибір геолокації або закладу.
chatActionChoosingContact—Вибір контакту.
chatActionStartPlayingGame—Початок гри.
chatActionRecordingVideoNote—Запис відеоповідомлення.
chatActionUploadingVideoNoteprogress: int32, 0–100Надсилання відеоповідомлення.
chatActionWatchingAnimationsemoji: stringНатискання анімованого emoji співрозмовника.
chatActionCancel—Скасування попередньої активності; також можна передати chat_action:null.

Типи без додаткових полів можна передавати рядком, наприклад "chat_action":"chatActionTyping". Для upload прогрес має тип integer; якщо відсутній, передається 0. Це повідомлення про активність: воно не завантажує файл і не починає запис мікрофона чи камери.

Усі типи MessageTopic

topic_id.@typeІдентифікатор
messageTopicThreadmessage_thread_id: int53
messageTopicForumforum_topic_id: int32
messageTopicDirectMessagesdirect_messages_chat_topic_id: int53
messageTopicSavedMessagessaved_messages_topic_id: int53; може бути від’ємним.

Для чату без теми передати topic_id:null. Ідентифікатори int53 можна передавати десятковими рядками. Підтримані також legacy WS-аліаси message_thread_id або forum_topic_id, які перетворюються в MessageTopic; не змішувати їх із topic_id чи між собою. Валідацію доступу до конкретної теми/чату виконує TDLib.

{"action":"send_chat_action","userbot_id":184,"chat_id":"-1001234567890","client_request_id":"upload-1",
 "topic_id":{"@type":"messageTopicForum","forum_topic_id":42},"business_connection_id":"BUSINESS_CONNECTION",
 "chat_action":{"@type":"chatActionUploadingDocument","progress":50}}
{"action":"send_chat_action","userbot_id":184,"chat_id":"12345","client_request_id":"emoji-1",
 "chat_action":{"@type":"chatActionWatchingAnimations","emoji":"👩🏽‍💻"}}
{"action":"send_chat_action","userbot_id":184,"chat_id":"12345","client_request_id":"typing-stop-1",
 "chat_action":null}

Флоу редактора та термін дії

Під час фактичного введення надсилати chatActionTyping і поновлювати приблизно раз на 4 секунди, якщо введення триває. Після паузи, відправлення, blur або переходу в інший діалог надсилати null чи chatActionCancel з тим самим chat/topic/business scope. Для запису й upload використовувати відповідні типи. Backend передає повторні дії та явні cancel; frontend має обмежити частоту подій клавіатури.

Це transient-команди: вони не потрапляють у ledger бізнес-мутацій і не повинні відтворюватися після reconnect. Gateway задає send_chat_action строк дії 5 секунд; прострочений запит повертає result.code:CHAT_ACTION_EXPIRED, некоректні параметри — INVALID_CHAT_ACTION. Не повторювати стару дію автоматично; нова реальна активність створює новий запит.

На старішій TDLib доступний сумісний plain-chat виклик без topic/business scope. Повний нативний MessageTopic/business контракт вимагає 1.8.70+: інакше повертається TDLIB_UPGRADE_REQUIRED, без втрати scope та надсилання в інший діалог. Вхідний updateChatAction залишається нативним tdlib_updates_v1 і відображається як раніше.

Стан діалогу: pinned, presence, typing, member count

Відкриття навколо повідомлення

{"action":"open_dialog","userbot_id":199,"chat_id":"-1001638813408",
 "center_message_id":"8032092160","window_before":20,"window_after":20,"pinned_limit":20}

pinned_limit працює в centered і tail-гілках. Backend надсилає до ліміту звичайних pinned_message; вони можуть прийти після pagination_setup. Завершення історії не означає завершення окремого pinned-потоку. Не відкривати tail повторно заради pinned; прив’язувати події до актуального акаунта, діалогу й dialog token.

Статус і активність поза відкритим чатом

updateUserStatus оновлює user store за (userbot_id,user_id) для всіх підписаних акаунтів. updateChatAction оновлює активність за акаунтом, chat/topic і sender. Читати нативні sender_id, action.@type, status; ім’я брати з user/chat entity store. Типізація та upload-активність тимчасові: cancel очищує стан, відсутність наступних подій потребує локального timeout. Повернення до чату не відновлює протермінований typing.

Лічильник учасників

get_chat_profile оновлює supergroup/full info та за доступності перевіряє кількість через мінімальний запит учасників. get_chats повертає доступний початковий зріз без очікування всього enrichment; уточнення надходять через chat-list updates. Не обходити весь список учасників на фронті заради counter. Оновлювати поле member_count, зберігаючи інші поля entity, і дотримуватися generation/revision та field watermarks з chat-list контракту.

Нативний updateSupergroupFullInfo і дані профілю також можуть уточнити header. Envelope та правила часткових оновлень — у native update reference.

GraphQL: аватари акаунтів та refresh_self_profile

Додати до наявних GraphQL-запитів наведені поля. У allUserbotsInUser додатково потрібний userId; дозволи та company scope залишаються чинними.

query AccountAvatars($companyId: Int!) {
  allUserbotsInCompany(companyId: $companyId) {
    id
    profilePhotoUrl
    profilePhotoRemoteId
    profilePhotoUniqueId
    profilePhotoMinithumbnail
  }
}
ПолеКонтракт і використання
profilePhotoUrlNullable URL збереженого фото. Storage key зберігається в backend; URL може перевидаватися. Null можливий без фото або до завершення фонового завантаження.
profilePhotoRemoteId / profilePhotoUniqueIdNullable рядки ідентичності фото; зміна інвалідовує frontend avatar cache. Не використовувати URL як єдину ідентичність фото.
profilePhotoMinithumbnailNullable base64 JPEG; для img додати data:image/jpeg;base64,. Якщо відсутній — ініціали.

Не відкривати клієнти всіх акаунтів заради аватарів: backend виконує обмежене фонове наповнення. Наявне збережене фото доступне через GraphQL незалежно від WS-підписки.

{"action":"refresh_self_profile","userbot_id":183,"client_request_id":"profile-1"}

Для відкритого акаунта відповідь refresh_self_profile.result містить profile_photo_url (може бути null), profile_photo_remote_id за наявності та profile_photo_pending_download. Refresh не чекає завантаження фото. За pending backend ставить його в спільну media queue для запитувача; використовувати чинний media_ready flow та звіряти file/remote identity. Окремої події avatar_ready немає. Після завершення наступний GraphQL-запит поверне URL збереженого фото; перезавантаження сторінки не вимагає нового open_client для цього URL. Не запускати необмежений polling для всіх акаунтів.

GraphQL: CRM та контакти мають окрему дію додавання

«Додати користувача в CRM» викликає createLead. Обов’язкові companyId, funnelId, stageId; передати наявний clientId або ідентичність telegramId, username, phoneNumber. Не викликати додатково createClient чи Telegram add/import contact.

mutation AddMessengerUserToCRM($companyId: ID!, $funnelId: ID!, $stageId: ID!, $telegramId: String!) {
  createLead(companyId: $companyId, funnelId: $funnelId, stageId: $stageId, telegramId: $telegramId) {
    lead { id }
  }
}

Backend перевикористовує існуючий Client у компанії. Якщо особа нова, створює CRM-only запис з raw_data._crm_only:true, який не входить у allClients. Наявний контакт зберігає членство й дані без дублювання; повторна заявка може бути відхилена звичною перевіркою дубля воронки.

Успішний createLead оновлює CRM UI, але сам по собі не додає рядок до contact store. Наявність Client у відповіді CRM або lookup не доводить, що це контакт. Явне createClient для CRM-only особи прибирає marker і додає її до контактів, зберігаючи Client ID. Видалення контакту зі зв’язаними лідами зберігає CRM-особу та ліди.

Помилки профілю та зайнята Telegram-ідентичність

GraphQL-запит user(id: Int!) повертає коди в errors[].extensions. Це семантика помилки резолвера; не покладатися лише на HTTP status GraphQL-відповіді.

extensionsСитуаціяТекст UI
code: NOT_FOUND, status: 404Користувач не існує.Користувача не знайдено.
code: FORBIDDEN, status: 403Користувач існує, але немає дозволу.У вас немає дозволу на перегляд цієї сторінки.

Обробляти ці випадки окремими сторінками/повідомленнями. Не показувати об’єднане «не знайдено або немає дозволу».

Конфлікт під час авторизації Telegram

{"type":"error","code":"DUPLICATE_TELEGRAM_ACCOUNT","conflict":"duplicate_phone",
 "terminal":true,"is_authenticated":false,"phone_number":"380000000000",
 "conflicting_userbot_id":198,"message":"This Telegram account is already in use in the system. To add it to the current company, contact the owner of the phone number."}

Backend перевіряє реальний Telegram ID і телефон до authorized; при конфлікті закриває auth WS з 4003 та відкликає сесію дубля. Початковий акаунт зберігає свою сесію. Frontend припиняє QR/code/password flow, не позначає дублікат авторизованим і оновлює список акаунтів.

Якщо конфлікт виявлено через refresh_self_profile, надходить refresh_self_profile_error з тими самими result.code/result.conflict, після чого account logged-out status. Прибрати runtime-стан дубля; не закривати початковий акаунт.

Текст для зайнятого номера: «Цей номер телефону вже використовується в системі. Якщо вам потрібно додати цей номер до поточної компанії, зверніться до власника номера телефону». Відсутність акаунта в списку поточної компанії не означає, що номер вільний глобально. Цей машинний auth-код не слід автоматично очікувати від GraphQL createUserbot: помилку його унікальності обробляти окремо. Повний auth flow — у довіднику авторизації.

Обмеження авторизації 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 елементи. Таймери повтору скасовувати при відписці чи зміні діалогу.

Terminal download_file_error при відмові native resolution містить result.error_code, result.native_method, result.native_error та result.retryable:false. Коди: MEDIA_FILE_RESOLUTION_FAILED або MEDIA_FILE_IDENTITY_CONFLICT. Не повторюйте такі запити таймером без оновлення file reference. remote_id — opaque ID; різні валідні значення можуть описувати один файл. Передавайте remote_unique_id з native remote.unique_id, якщо він відомий, або збережіть native object remote:{id,unique_id}; не копіюйте remote_id у unique_id.

Результат команди завжди адресований початковому 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 updates: presence, typing та message interactions

Статус і typing надходять у нативному tdlib_updates_v1 envelope для всіх підписаних акаунтів. sender_id є messageSenderUser/messageSenderChat; ім’я брати з entity store, без очікування старих enriched aliases. Обробку закритих діалогів описано в контракті стану діалогу.

updateMessageInteractionInfo частково оновлює повідомлення за (userbot_id,chat_id,message_id): замінити interaction_info, зберегти content; явний null очищує interaction info. Реакції читати як нативні interaction_info.reactions.reactions[] з type, total_count, is_chosen, recent_sender_ids. Поля, відсутні в події, не очищувати.

updateMessageReactions зберігає власну нативну структуру. Не використовувати старі results, chosenOrder чи enriched sender aliases. Повний список авторів отримувати на вимогу через get_message_reaction_senders. Приклади envelope і правила reducer — у native reference.

Client Session

ActionЩо приймаєЩо повертаєЩо робить
open_client userbot_ids (повний набір, [] відписує всі) або userbot_id; опц. client_request_id open_client_ready: active/added/retained/removed IDs, binding_generations, echoed client_request_id Замінює набір NATS підписок. Retained accounts зберігають binding і pending responses; startup лише для нових прив'язок або неприйнятого startup. Повтор набору повертає ack без переініціалізації. Для адресної WS-відповіді з актуальним self profile окремо викликати {"action":"refresh_self_profile","userbot_id":4} після open_client_ready; open_client її автоматично не надсилає. ТЗ bootstrap/sync і frontend timers.
refresh_self_profile userbot_id refresh_self_profile / refresh_self_profile_error Оновлює локальний UserBot з TDLib getMe. Повертає знімок профілю без очікування фото; аватар завантажується спільною обмеженою медіачергою, після чого фонова задача зберігає об’єкт і ключ у UserBot.profile_photo_path. Повертає profile_photo_url, profile_photo_remote_id, profile_photo_unique_id і profile_photo_minithumbnail (base64 JPEG). Поки фото готується або при збої зберігає попередній URL та повертає profile_photo_pending_download:true; media_ready надає завантажене фото, а наступний GraphQL-запит — постійний об’єкт; видалення фото в Telegram очищає URL. GraphQL allUserbotsInCompany / allUserbotsInUser віддають profilePhotoUrl і опційні profilePhotoRemoteId, profilePhotoUniqueId, profilePhotoMinithumbnail без WS-підписки. Для старих акаунтів без збереженого фото заповнення виконується у фоні; до завершення першого завантаження URL може бути null, наступний GraphQL-запит поверне збережене фото. Фоновий refresh не відкриває чат-листи або picker. Для одного акаунта sync послідовний; дубльований телефон повертає refresh_self_profile_error з conflict: duplicate_phone.
get_active_sessions userbot_id get_active_sessions / get_active_sessions_error Повертає активні Telegram-сесії поточного акаунта. У відповіді є sessions, current_session, current_session_id, other_sessions, count і inactive_session_ttl_days. ID — рядки зі знаковим int64, включно з "0". Контракт поточного сеансу. Також приймається alias get_sessions.
terminate_session userbot_id, session_id terminate_session / terminate_session_error Завершує конкретну Telegram-сесію за session_id. Також приймається alias delete_session.
set_session_settings userbot_id, session_id, опц. can_accept_calls, can_accept_secret_chats set_session_settings / set_session_settings_error Оновлює налаштування конкретної сесії. Можна окремо перемикати прийом дзвінків і нових secret chats. Потрібно передати хоча б одне поле. Також приймається alias update_session_settings.
terminate_all_other_sessions userbot_id terminate_all_other_sessions / terminate_all_other_sessions_error Завершує всі інші Telegram-сесії, крім поточної. Також приймається alias terminate_all_sessions.

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

{
  "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}

Активні сеанси: поточний пристрій та завершення інших

TDLib session.id має тип int64: нульові та від’ємні значення допустимі. Backend зберігає їх десятковими рядками в sessions[].id, current_session.id, current_session_id, other_sessions[].id та відповідях мутацій. Не перетворювати ID на JavaScript Number: великі значення втрачають точність. Запити приймають session_id рядком або цілим числом у межах int64.

{"userbot_id":184,"type":"get_active_sessions","result":{
 "@type":"sessions","sessions":[
   {"@type":"session","id":"0","is_current":true,"application_name":"akva.club"},
   {"@type":"session","id":"-8843137603905177123","is_current":false,"application_name":"Telegram Desktop"}],
 "count":2,"current_session":{"@type":"session","id":"0","is_current":true,"application_name":"akva.club"},
 "current_session_id":"0","other_sessions":[
   {"@type":"session","id":"-8843137603905177123","is_current":false,"application_name":"Telegram Desktop"}],
 "other_sessions_count":1,"inactive_session_ttl_days":183}}

Поточний сеанс визначається нативним is_current, без підміни назви застосунку чи пристрою. Він входить у sessions, але не other_sessions; порядок TDLib зберігається. Якщо TDLib справді не повернув поточний сеанс, backend не вигадує його: current_session/current_session_id залишаються null.

Frontend flow: get_active_sessions → блок «Цей пристрій» за is_current, окремо other_sessions. Після terminate_all_other_sessions повторити get_active_sessions; залишиться поточний сеанс, якщо інші пристрої не авторизувалися знову. Форма WS-відповідей і client_request_id збережені.

Завершення інших виконується одним TDLib terminateAllOtherSessions, без циклу terminateSession для кожного пристрою. Поля terminated_session_ids/terminated_count описують попередній доступний зріз; якщо його отримати не вдалося, вони відсутні. Остаточний перелік — у повторному get_active_sessions. terminate_session захищає поточний сеанс; для виходу використовується окремий logOut flow. set_session_settings також приймає нульовий і від’ємні ID.

Channel Commands

ActionЩо приймаєЩо повертаєЩо робить
get_chats userbot_id, опц. chat_list, limit (1–100, default 50) Один get_chats: entities, chat_ids, generation, revision, load state Atomic bootstrap cut без enrichment. Main можна показати одразу. Frontend ТЗ.
load_chats userbot_id, chat_list, limit, опц. after:{order,chat_id} load_chats з компактною сторінкою або load_chats_error Cached page або одна loadChats порція. Кінець: !has_more_cached і list_exhausted.
get_chat_list_entities userbot_id, entity_keys (до 100) chat_list_entities, mode=hydrate Atomic batch lookup без native I/O; entity watermark не пересуває account cursor.
sync_chat_list userbot_id, generation, since_revision, опц. change_limit chat_list_sync: changes, revision, target_revision, has_more, reset_required Replay account-wide entity changes; при reset отримати новий bootstrap.
get_recently_opened_chats userbot_id, опц. limit get_recently_opened_chats (потік елементів чату), або get_recently_opened_chats_error Віддає нещодавно відкриті приватні чати (TDLib getRecentlyOpenedChats + фільтр chatTypePrivate).
archive_chat userbot_id, chat_id archive_chat / archive_chat_error Переміщає чат в архів.
unarchive_chat userbot_id, chat_id unarchive_chat / unarchive_chat_error Повертає чат в main list.
pin_chat userbot_id, chat_id, опц. is_pinned, chat_list pin_chat / pin_chat_error Закріплює або відкріплює чат у списку. chat_list — native object з @type; рядкові aliases не приймаються.
set_pinned_chat_position userbot_id, chat_id, position, опц. chat_list set_pinned_chat_position / set_pinned_chat_position_error Змінює порядок уже закріпленого чату. chat_list — native object з @type. position нуль-індексована; backend атомарно передає повний актуальний порядок у TDLib setPinnedChats.
chat_in_folder userbot_id, chat_id, chat_folder_id, опц. added/removed/pin/unpin chat_in_folder / chat_in_folder_error Керує членством чату у folder list.
create_chat_folder userbot_id, title (або name), опц. icon_name/icon, color_id, is_shareable, pinned_chat_ids[], included_chat_ids[], excluded_chat_ids[], флаги include_*/exclude_* create_chat_folder / create_chat_folder_error Створює нову папку чатів через TDLib createChatFolder.
get_chats_for_chat_folder_invite_link userbot_id, chat_folder_id get_chats_for_chat_folder_invite_link / get_chats_for_chat_folder_invite_link_error Повертає список чатів, які можна включити в invite link папки (TDLib get_chats_for_chat_folder_invite_link).
get_chat_folder_invite_links userbot_id, chat_folder_id get_chat_folder_invite_links / get_chat_folder_invite_links_error Повертає список існуючих invite links для папки (TDLib get_chat_folder_invite_links).
create_chat_folder_invite_link userbot_id, chat_folder_id, опц. name, chat_ids[] (або chatIds[]) create_chat_folder_invite_link / create_chat_folder_invite_link_error Створює нове invite link для папки через TDLib create_chat_folder_invite_link.
edit_chat_folder_invite_link userbot_id, chat_folder_id, invite_link, опц. name, chat_ids[] (або chatIds[]) edit_chat_folder_invite_link / edit_chat_folder_invite_link_error Редагує invite link папки через TDLib editChatFolderInviteLink.
delete_chat_folder_invite_link userbot_id, chat_folder_id, invite_link delete_chat_folder_invite_link / delete_chat_folder_invite_link_error Видаляє invite link папки через TDLib deleteChatFolderInviteLink.
delete_chat userbot_id, chat_id, опц. revoke, remove_from_chat_list delete_chat / delete_chat_error Викликає deleteChatHistory і при успіху інвалідує кеш списку чатів, діалогу, raw history, chat info/profile та forum topics. Success payload містить chat_id, revoke, remove_from_chat_list.
delete_channel userbot_id, chat_id (або channel_id як alias того ж chat id) delete_channel / delete_channel_error Повністю видаляє канал для всіх учасників через TDLib deleteChat; доступно лише власнику, коли can_be_deleted_for_all_users=true. При успіху інвалідує кеш чату.
leave_chat userbot_id, chat_id leave_chat / leave_chat_error Вихід із групи/каналу.

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, chat_id, опц. from_message_id, message_thread_id, limit, offset, center_message_id, window_before, window_after, pinned_limit Потік: fast open_dialog з повідомленнями → dialog_chat_info → pagination_setup; dialog_end лише коли старішої історії більше немає. Додаткові pinned_message, dialog_comments, dialog_reply_meta можуть надходити пізніше. Custom emoji у fast history містять identity (emoji_id), type, offset і length без inline custom_emoji_media чи token URL. Після повідомлень і preview backend фоново подає унікальні emoji ID у чинний media-флоу: готові ресурси надходять окремими media_ready з kind=custom_emoji та emoji_id через media WS. Один ID подається один раз у межах prewarm batch; custom_emoji_prewarm_limit обмежує автоматичний prewarm (типово 24, 0 вимикає). Frontend зберігає ресурс за (userbot_id, emoji_id) і застосовує його до всіх відповідних entities; решту видимих emoji може запросити через get_custom_emoji_media. Зміна діалогу припиняє подальший prewarm старого scope. Повідомлення містять author_signature, якщо в каналі ввімкнені підписи; окремий dialog_chat_info містить sign_messages і show_message_sender. open_dialog є read-only: завантаження history саме по собі не викликає viewMessages і не зменшує unread counter. Поле pagination_setup.unread_message_ids лише допомагає frontend визначити unread елементи; після фактичного показу потрібно явно викликати mark_messages_as_read тільки з видимими ID. У chat-list item поле preview.thumbs[] для photo/video/animation/document/audio/video-note/sticker містить нормалізований media minithumbnail. У пересланому повідомленні forwardInfo.avatar і forwardInfo.minithumbnail належать origin sender-у; thumbnail пересланого медіа залишається у кореневому minithumbnail та content[]. older_state/newer_state: more — знайдено сусіднє повідомлення; exhausted — підтверджено межу; unknown — перевірка не завершена або сталася помилка. У стані more поля next_older_id/next_newer_id містять сусідні ID. За unknown курсор може бути межею поточної сторінки (next_older_is_boundary/next_newer_is_boundary); наступну сторінку потрібно об’єднувати за message ID. has_older=null означає невизначеність, а не кінець. Повтор після тимчасової помилки виконуйте з backoff; не запускайте нескінченну автоматичну пагінацію без просування курсора. Курсори, unread IDs і стани меж передаються лише в pagination_setup; у open_dialog/open_comments їх немає. Ліміт сторінки — 1–100 повідомлень. pagination_setup завершує порцію history; індикатор завантаження не повинен чекати dialog_end. Подія dialog_end завжди має has_older=false, is_history_end=true і враховує межу історії topic. Коротка сторінка та кеш самі по собі не означають кінець історії.
get_forum_topics userbot_id, chat_id get_forum_topics / get_forum_topics_error Повертає окремим запитом список topic payload для forum/supergroup. Використовуйте для екрана списку тем замість побічного payload з open_dialog.
create_forum_topic userbot_id, chat_id, name/title, опц. icon, icon_color, icon_custom_emoji_id create_forum_topic / create_forum_topic_error Створює тему через TDLib createForumTopic та очищає кеш тем.
edit_forum_topic userbot_id, chat_id, message_thread_id (також forum_topic_id/topic_id/thread_id), опц. name/title, edit_icon_custom_emoji_id, icon_custom_emoji_id edit_forum_topic / edit_forum_topic_error Редагує назву або custom emoji теми через TDLib editForumTopic.
delete_forum_topic userbot_id, chat_id, ID теми як message_thread_id/forum_topic_id/topic_id/thread_id delete_forum_topic / delete_forum_topic_error Видаляє тему через TDLib deleteForumTopic та очищає кеш тем.
close_forum_topic userbot_id, chat_id, ID теми як message_thread_id/forum_topic_id/topic_id/thread_id close_forum_topic / close_forum_topic_error Закриває тему через toggleForumTopicIsClosed. Success payload містить chat_id, message_thread_id, is_closed:true.
open_forum_topic userbot_id, chat_id, ID теми як message_thread_id/forum_topic_id/topic_id/thread_id open_forum_topic / open_forum_topic_error Повторно відкриває тему через toggleForumTopicIsClosed. Success payload містить chat_id, message_thread_id, is_closed:false.
pin_forum_topic / unpin_forum_topic userbot_id, chat_id, ID теми як message_thread_id/forum_topic_id/topic_id/thread_id pin_forum_topic / unpin_forum_topic або відповідний *_error Закріплює або відкріплює тему через TDLib toggleForumTopicIsPinned. Success payload містить chat_id, message_thread_id, is_pinned.
open_comments userbot_id, comments_meta або discussion_chat_id + message_thread_id, опц. from_message_id, limit, offset, center_message_id, window_before, window_after, pinned_limit Потік: dialog_access, comments_access, open_comments з messages[], pagination_setup; dialog_end лише за відсутності старішої історії; або dialog_empty/dialog_error Відкриває comments thread поста в linked discussion chat. comments_access містить ті самі ефективні права, що й dialog_access, плюс discussion_chat_id і message_thread_id для comments composer.
search_messages_in_chat Звичайний режим: userbot_id, chat_id, опц. query, sender_id, sender_type (user/chat), filter/search_filter, limit (1..100), from_message_id, offset (мін. -1), message_thread_id, date_from/from_date, date_to/to_date. Джерела «Збереженого»: userbot_id + search_mode:"saved_source_chats" або saved_sources_only:true. Повідомлення вибраного джерела: додайте source_chat_id/saved_source_chat_id або saved_messages_topic_id; також підтримується search_mode:"saved_source_messages". search_messages_in_chat / search_messages_in_chat_error Пошук через TDLib searchChatMessages. sender_id нативно фільтрує за відправником: додатний ID за замовчуванням є user; для sender-чату/каналу передайте sender_type:"chat" (від’ємний ID автоматично вважається chat). Фільтр сумісний із query, date range, topic, media filter та pagination. У Saved Messages source modes sender_id не підтримується. Межі дат включні та приймають Unix seconds/milliseconds, YYYY-MM-DD або ISO-8601.
search_messages_global userbot_id, опц. query, filter/search_filter, limit, offset_date, offset_chat_id, offset_message_id, chat_list search_messages_global / search_messages_global_error Глобальний пошук повідомлень по діалогах через TDLib searchMessages з підтримкою searchMessagesFilter* і поверненням нормалізованих message payload.
get_message_viewers / get_message_reads userbot_id, chat_id, message_id (alias msg_id) get_message_viewers / get_message_viewers_error Повертає доступний Telegram список тих, хто переглянув повідомлення: viewers[], count, дані користувача, is_bot, avatar remote id, view_date і view_timestamp. Telegram може не розкривати viewers для конкретного чату або повідомлення.
get_message_read_date / get_private_message_read_date userbot_id, chat_id, message_id (alias msg_id) get_message_read_date / get_message_read_date_error Повертає точний час прочитання недавнього вихідного повідомлення в особистому чаті через TDLib getMessageReadDate. Success містить status, is_read, read_date, read_timestamp, read_at_is_estimated:false. Можливі статуси read, unread, too_old, my_privacy_restricted, user_privacy_restricted.
get_chat_recent_actions userbot_id, chat_id, опц. query, from_event_id, limit, user_ids[], event_filters get_chat_recent_actions / get_chat_recent_actions_error “Недавні дії” (TDLib getChatEventLog) для каналу/супергрупи. Повертає сирі події логу та next_from_event_id для пагінації. Потребує прав адміністратора.

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

{"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Що знайдеВкладка UI (приклад)
searchMessagesFilterEmptyЗвичайний пошук без типового фільтра.Усі
searchMessagesFilterAnimationАнімації.Медіа
searchMessagesFilterAudioАудіо.Медіа
searchMessagesFilterDocumentДокументи/файли.Файли
searchMessagesFilterPhotoФото.Медіа
searchMessagesFilterVideoВідео.Медіа
searchMessagesFilterVoiceNoteVoice.Голосові
searchMessagesFilterPhotoAndVideoФото + відео.Медіа
searchMessagesFilterUrlПовідомлення з URL.Посилання
searchMessagesFilterChatPhotoОновлення фото чату.Системні
searchMessagesFilterVideoNoteVideo note.Голосові
searchMessagesFilterVoiceAndVideoNoteVoice + video note.Голосові
searchMessagesFilterMentionЗгадки.Мітки
searchMessagesFilterUnreadMentionНепрочитані згадки.Мітки
searchMessagesFilterUnreadReactionНепрочитані реакції.Мітки
searchMessagesFilterFailedToSendНе відправлені повідомлення.Чернетки/помилки

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ПоляПризначення
get_chat_notification_settingsuserbot_id, chat_idПоточні налаштування чату разом із is_muted, mute_until, is_muted_forever.
set_chat_notification_settingschat_id, notification_settings або окремі поляЧастково змінює message/story preview, sounds, mute, mention та pinned-message notifications.
mute_chat / unmute_chatchat_id; для mute — mute_for/durationШвидкий mute на секунди, 1h, 8h, 3d, forever, або unmute.
reset_chat_notification_settingschat_idПовертає всі chat overrides до відповідного глобального scope.
get_scope_notification_settings / set_scope_notification_settingsscope: private, group, channelГлобальні налаштування типу чатів.
get_chat_notification_settings_exceptionsопц. scope, compare_soundЧати з settings, що відрізняються від scope defaults.
get_forum_topic_notification_settings / set_forum_topic_notification_settingschat_id, message_thread_id, для set — settingsЧитає або частково змінює окремі налаштування forum topic. Кожен item у get_forum_topics також містить актуальний об’єкт notification_settings.
mute_forum_topic / unmute_forum_topicchat_id, message_thread_id; для mute опц. mute_for/duration або mute_untilМутить лише вибраний topic, не весь чат. Без тривалості mute_forum_topic використовує forever; unmute встановлює mute_for=0.
set_reaction_notification_settingsmessage_reaction_source, story_reaction_source, sound_id, show_previewДжерела all/contacts/none для реакцій.
get_saved_notification_sounds / get_saved_notification_soundдля single — notification_sound_idСписок або один Telegram custom notification sound.
add_saved_notification_sound / remove_saved_notification_soundfile_id/remote_id; для remove — notification_sound_idДодає або видаляє custom sound.
reset_all_notification_settingsuserbot_idСкидає всі chat і scope settings до Telegram defaults.
configure_notification_apinotification_group_count_max (0–25), notification_group_size_max (1–25)Opt-in в active Notification API; count=0 вимикає її.
remove_notificationnotification_group_id, notification_idПідтверджує TDLib, що користувач прибрав одне активне сповіщення.
remove_notification_groupnotification_group_id, max_notification_idПідтверджує видалення групи активних сповіщень до вказаного ID.
{"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Що приймаєЩо повертаєЩо робить
get_available_senders userbot_id, chat_id get_available_senders / get_available_senders_error Повертає профілі, від імені яких можна писати: sender_chat_id, sender_user_id, sender_type, title, avatar, subscriber_count, needs_premium, is_selected.
send_message userbot_id, chat_id, text, опц. entities, media/media_items, poll, reply_to, options, send_as_chat_id send_message / send_message_error Відправляє текст, media або poll. send_as_chat_id вибирає автора з get_available_senders. Для локального upload flow див. Media Uploads.
create_poll / send_poll userbot_id, chat_id, question, poll_options[] або poll; опц. poll_type, is_anonymous, allows_multiple_answers, correct_option_id, explanation, open_period, close_date, is_closed create_poll / create_poll_error, send_poll / send_poll_error Створює Telegram poll через TDLib inputMessagePoll. У WS можна передавати question і poll_options звичайними рядками. Backend формує question як formattedText, кожен варіант як {"@type":"inputPollOption","text":{"@type":"formattedText","text":"Варіант"}}, а type — inputPollTypeRegular або inputPollTypeQuiz. Для regular прапорець allows_multiple_answers розташований у inputMessagePoll. Для quiz публічний correct_option_id перетворюється на native correct_option_ids; індекси починаються з нуля. Explanation зберігається як formattedText. Порожні варіанти відхиляються без зміщення правильних індексів.
set_poll_answer / answer_poll userbot_id, chat_id, message_id, option_ids[] або option_id set_poll_answer / set_poll_answer_error Відправляє або змінює відповідь поточного користувача на poll через TDLib setPollAnswer.
get_poll_voters userbot_id, chat_id, message_id/msg_id; опц. max_voters_per_option get_poll_voters / get_poll_voters_error Посторінково викликає TDLib getPollVoters для кожної опції неанонімного poll. Повертає плоский voters[] і згрупований options[].voters[] з option, ID, імʼям, username та аватаркою. У payload звичайного messagePoll глобальний recent_voter_ids уже містить збагачені профілі, а кожна option має до 3 останніх voter-ів у recent_voters/recent_voter_ids з avatar і minithumbnail. TDLib не повертає час окремого голосу, тому vote_time_available=false, а vote_date/vote_timestamp дорівнюють null.
stop_poll userbot_id, chat_id, message_id, опц. reply_markup stop_poll / stop_poll_error Зупиняє poll через TDLib stopPoll, якщо повідомлення можна редагувати.
send_comment userbot_id, comments_meta або discussion_chat_id + message_thread_id, і той самий payload, що для send_message: text, entities, media, media_items, media_type, reply_to, reply_to_message_id, reply_markup, options, schedule_date, send_when_online, effect_id, message_effect_id, send_large_photos, тощо send_comment / send_comment_error Відправляє повідомлення в comments thread поста. Підтримує той самий набір текстових, media і send-options полів, що й send_message; різниця лише в target thread.
edit_message userbot_id, chat_id, message_id, text, опц. entities, media, media_type, reply_markup edit_message / edit_message_error Редагує текст або single-media повідомлення. Для media використовує той самий local-upload payload, що й send_message; media_items не підтримується.
delete_messages userbot_id, chat_id, message_ids[], опц. revoke delete_messages / delete_messages_error Видаляє один або кілька меседжів.
mark_messages_as_read userbot_id, chat_id, один message_id/msg_id або message_ids[]; опц. message_thread_id, force_read mark_messages_as_read / mark_messages_as_read_error Передає тільки задані message ID у TDLib viewMessages. Підходить для читання одного видимого повідомлення або batch видимих повідомлень без команди прочитати весь чат. Alias-и view_message/view_messages збережені.
reply_message userbot_id, chat_id, reply_to_message_id, text reply_message / reply_message_error Відправляє reply на конкретний message.
forward_message userbot_id, to_chat_ids[], from_chat_id, message_ids[], опц. send_copy/without_sender, remove_caption/without_caption, new_caption, show_caption_above_media forward_message / forward_message_error Форвардить повідомлення в один або кілька чатів одним TDLib forwardMessages batch на цільовий чат. Якщо message_ids[] містить усі елементи source-альбому, Telegram зберігає їх як один альбом і призначає спільний новий media_album_id. Result кожного елемента містить forwarded_message_id та media_album_id; нормалізовані message events містять однакові alias-и album_id і media_album_id. Підтримує режим “без імені відправника” і “без опису”.
pin_message userbot_id, chat_id, message_id, опц. disable_notification, only_for_self pin_message / pin_message_error Закріплює message у чаті.
unpin_message userbot_id, chat_id, message_id unpin_message / unpin_message_error Відкріплює message.
set_reaction userbot_id, chat_id, message_id, reaction, опц. is_big, add_to_recent set_reaction / set_reaction_error Ставить реакцію на message через TDLib addMessageReaction (emoji/custom emoji/paid).
remove_reaction / remove_message_reaction userbot_id, chat_id, message_id, реакція як reaction, emoji або custom_emoji_id/emoji_id remove_reaction / remove_reaction_error Прибирає власну реакцію через TDLib removeMessageReaction. remove_message_reaction є alias; response type — remove_reaction.
get_message_reaction_senders / get_reaction_senders userbot_id, chat_id, message_id, опц. reaction/emoji/custom_emoji_id get_message_reaction_senders / get_message_reaction_senders_error Завантажує всі сторінки авторів реакцій і повертає senders[], reactions[], лічильники та is_complete. Telegram може не розкрити анонімних авторів.
get_chat_reaction_settings userbot_id, chat_id. Alias: get_channel_reaction_settings. get_chat_reaction_settings / get_chat_reaction_settings_error Повертає поточні available_reactions, permissions і can_enable_paid_reaction для UI налаштувань реакцій.
set_chat_reaction_settings userbot_id, chat_id, опц. mode (all/some/none), reactions[], max_reaction_count, enable_reactions, enable_paid_reactions. Alias-и: set_channel_reaction_settings, set_chat_available_reactions, set_chat_reactions, set_channel_reactions. set_chat_reaction_settings / set_chat_reaction_settings_error Оновлює реакції чату/каналу через TDLib setChatAvailableReactions: вмикає/вимикає реакції, задає whitelist реакцій, максимум реакцій на message і paid reaction.
enable_chat_reactions / disable_chat_reactions userbot_id, chat_id, опц. max_reaction_count. Для каналів також є alias-и enable_channel_reactions, disable_channel_reactions. set_chat_reaction_settings / set_chat_reaction_settings_error Швидкі alias-и для вмикання всіх реакцій або повного вимикання реакцій.
set_chat_max_reaction_count userbot_id, chat_id, max_reaction_count або count (бекенд обмежує значення до 1..11). set_chat_reaction_settings / set_chat_reaction_settings_error Змінює тільки максимум реакцій, зберігаючи поточний режим available_reactions.
set_chat_paid_reactions userbot_id, chat_id, опц. enabled/enable_paid_reactions. Alias: set_channel_paid_reactions. set_chat_reaction_settings / set_chat_reaction_settings_error Додає або прибирає reactionTypePaid у доступних реакціях. Якщо поточний режим all, бекенд розгортає його у список доступних реакцій через getAvailableReactions і додає paid reaction.
get_callback_query_answer userbot_id, chat_id, message_id, data або готовий TDLib payload, опц. data_encoding (base64 / utf-8), requires_password, password get_callback_query_answer / get_callback_query_answer_error Натискає inline callback-кнопку через TDLib getCallbackQueryAnswer. Для кнопок з callback data передавайте data і data_encoding. Якщо action кнопки містить requires_password:true, передайте цей boolean і password — пароль двоетапної перевірки поточного Telegram-акаунта. Backend формує callbackQueryPayloadDataWithPassword; пароль не обрізається, не хешується application-кодом і не повертається у відповіді. TDLib сам виконує перевірку пароля. Для готового payload пароль має бути всередині {"@type":"callbackQueryPayloadDataWithPassword","password":"…","data":"BASE64"}; top-level data_encoding не змінює encoding готового payload.

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

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

Відправка у forum topic

Для send_message і polls підтримується явний native topic_id object або forum_topic_id. Вони визначають destination без metadata lookup. Чинний frontend payload з message_thread_id також працює: owner через async account metadata визначає forum чи discussion і формує відповідний MessageTopic. Помилка metadata припиняє send; непізнана гілка не перетворюється на відправку в General. На native boundary застаріле кореневе message_thread_id більше не надсилається.

{"action":"send_message","userbot_id":1,"chat_id":"-1003858417929","text":"Флай","topic_id":{"@type":"messageTopicForum","forum_topic_id":18}}

Текст, медіа, album та відокремлений довгий album caption використовують ту саму destination. send_comment явно формує messageTopicThread, навіть якщо discussion supergroup має forum topics. reply_to залишається окремим посиланням на повідомлення; для відправки в forum topic reply не потрібен.

reply_message також приймає topic_id, forum_topic_id або message_thread_id; позитивний reply_to_message_id обов’язковий. Для channel direct messages передавайте topic_id:{"@type":"messageTopicDirectMessages","direct_messages_chat_topic_id":77}. Конфлікт між явним topic та іншими destination IDs завершується помилкою до відправки.

{"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"]}

Якщо TDLib повернув null для окремого forwarded message, відповідний item має success:false, а команда повертає forward_message_error з невдалими ID. Успішно переслані повідомлення автоматично повторно не надсилаються.

{"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, file_id, опц. source, chat_id, msg_id, message_thread_id, extra, queue_priority download_file (ack), далі media_ready; або download_file_error Запускає ручне завантаження файлу. Після готовності надсилає шлях/мета в media_ready.
get_custom_emoji_media userbot_id, custom_emoji_ids[], опц. request_id get_custom_emoji_media (ack), далі media_ready; або get_custom_emoji_media_error Приймає до 512 унікальних custom emoji ID. Ack містить items:[{emoji_id,set_id}]; готові ресурси надходять окремими media_ready через чинний медіа-WS.

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

{"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"}

Єдиний native-контракт стікерів, емодзі та animations

Кожен action нижче має один шлях: WS → picker command → TDLib. Відповідь у chat_update.payload: type=<action>, result — об’єкт TDLib. Помилка: type=<action>_error, error, опц. result.error_code, result.outcome_unknown. Зміни використовують стабільний command_id або client_request_id. Невідомий результат не можна повторювати з новим ID.

sticker_type — native-об’єкт {"@type":"stickerTypeRegular"}, {"@type":"stickerTypeCustomEmoji"} або {"@type":"stickerTypeMask"}. sticker/animation — {"@type":"inputFileRemote","id":"REMOTE_ID"} або {"@type":"inputFileId","id":123}. set_id, custom emoji ID та масиви ID наборів передавайте рядками int64. Shorthand-рядки типів, raw remote_id, alias-поля й невідомі параметри не приймаються.

ActionNative-параметри крім userbot_idРезультат TDLibМетодМутація
get_sticker_setset_id: int64StickerSetgetStickerSetНі
search_sticker_setname: string, ignore_cache: Bool (типово false)StickerSetsearchStickerSetНі
get_archived_sticker_setssticker_type: StickerType, offset_sticker_set_id: int64, limit: int32StickerSetsgetArchivedStickerSetsНі
get_trending_sticker_setssticker_type: StickerType, offset: int32, limit: int32TrendingStickerSetsgetTrendingStickerSetsНі
search_sticker_setssticker_type: StickerType, query: stringStickerSetssearchStickerSetsНі
change_sticker_setset_id: int64, is_installed: Bool, is_archived: BoolOkchangeStickerSetТак
reorder_installed_sticker_setssticker_type: StickerType, sticker_set_ids: vector<int64>OkreorderInstalledStickerSetsТак
get_favorite_stickersНемаєStickersgetFavoriteStickersНі
add_favorite_stickersticker: InputFileOkaddFavoriteStickerТак
remove_favorite_stickersticker: InputFileOkremoveFavoriteStickerТак
remove_recent_stickeris_attached: Bool, sticker: InputFileOkremoveRecentStickerТак
clear_recent_stickersis_attached: BoolOkclearRecentStickersТак
get_stickerssticker_type: StickerType, query: string, chat_id: int53, limit: int32StickersgetStickersНі
search_stickerssticker_type: StickerType, emojis: string, query: string, input_language_codes: vector<string>, offset: int32, limit: int32StickerssearchStickersНі
get_emoji_categoriestype: EmojiCategoryTypeEmojiCategoriesgetEmojiCategoriesНі
search_emojistext: string, input_language_codes: vector<string>EmojiKeywordssearchEmojisНі
get_installed_sticker_setssticker_type: StickerTypeStickerSetsgetInstalledStickerSetsНі
get_recent_stickersis_attached: BoolStickersgetRecentStickersНі
get_saved_animationsНемаєAnimationsgetSavedAnimationsНі
add_saved_animationanimation: InputFileOkaddSavedAnimationТак
remove_saved_animationanimation: InputFileOkremoveSavedAnimationТак
search_gifsquery: string, offset: stringInlineQueryResultsgetInlineQueryResultsНі

Native-пагінація та результати

Приклади

{"action":"get_installed_sticker_sets","userbot_id":183,"sticker_type":{"@type":"stickerTypeCustomEmoji"}}
{"action":"get_sticker_set","userbot_id":183,"set_id":"9007199254740993"}
{"action":"search_sticker_set","userbot_id":183,"name":"Animals","ignore_cache":false}
{"action":"change_sticker_set","userbot_id":183,"set_id":"9007199254740993","is_installed":true,"is_archived":false,"command_id":"install-1"}
{"action":"add_favorite_sticker","userbot_id":183,"sticker":{"@type":"inputFileRemote","id":"REMOTE_ID"},"command_id":"favorite-1"}
{"action":"add_saved_animation","userbot_id":183,"animation":{"@type":"inputFileId","id":123},"command_id":"save-animation-1"}

GIF-пошук

search_gifs — єдиний прикладний workflow: query/offset передаються у getInlineQueryResults після визначення бота за TDLib option animation_search_bot_username. Немає hardcoded fallback-бота або альтернативного search action. Порожній query запитує початкову добірку бота. Результат — native inlineQueryResults: results, next_offset та інші поля. Animation міститься у results[].animation.animation. Cursor next_offset непрозорий; limit та q не приймаються.

Єдиний media flow

Для native-файла стікера беріть sticker.id/sticker.remote.id; для animation — animation.id/animation.remote.id. Передавайте file_id/remote_id у чинний download_file; готовий ресурс надходить через медіа-WS як media_ready. Для premium animation використовуйте native full_type.premium_animation. Для повторного пошуку файла набору можна передати extra.set_id та extra.remote_unique_id: backend читає набір через той самий picker gateway.

Custom emoji ID — full_type.custom_emoji_id, набір — native set_id. Окремий get_custom_emoji_media керує лише доставкою asset: до 512 ID, ack items:[{emoji_id,set_id}], потім media_ready{emoji_id,set_id,path,...}. Для metadata використовується один account-bound запис і один batch coordinator. Новий та cached asset мають однаковий media_ready. Відсутній набір у цьому media-event — set_id:null.

Події з телефону

На control-WS з open_client для акаунта надходять native updateInstalledStickerSets, updateFavoriteStickers, updateRecentStickers, updateSavedAnimations, updateStickerSet, updateTrendingStickerSets. Відкритий діалог не потрібен. Після події перечитайте відповідний canonical action. Списки повертає актуальний state TDLib; Redis-кешів списків, stale fill і відновлення старих picker envelope немає.

Prewarm використовує ті самі picker-команди та native covers. Він не створює окремого контракту і не завантажує вміст кожного встановленого набору.

Подія 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","set_id":"9007199254740993","kind":"custom_emoji","path":"https://.../media/opaque-token","format":"webm","file_format":"webm","sticker_format":"webm","storage_extension":".webm","content_type":"video/webm","request_id":"composer-emoji-pack","batch_index":1,"batch_total":2}}

Для custom emoji приходять emoji_id, set_id, kind=custom_emoji, path, format/file_format/sticker_format (webp/tgs/webm), storage_extension та MIME. Якщо передані, зберігаються request_id, batch_index, batch_total. Формат визначайте за метаданими, а не за token URL.

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

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

User / Chat Profiles / Contacts

ActionЩо приймаєЩо повертаєЩо робить
search_user userbot_id, username search_user / search_user_error Пошук публічного чату/юзера за username. Підтримує і durov, і @durov.
search_chats_global userbot_id, query (або title/username), опц. limit search_chats_global / search_chats_global_error Глобальний пошук чатів по title і username через TDLib searchChats, searchChatsOnServer і searchPublicChats. Повертає масив items у форматі chat-list.
create_private_chat userbot_id, user_id (або tg_user_id), опц. force create_private_chat / create_private_chat_error Створює або повертає приватний чат через TDLib createPrivateChat. Повернений chat_id використовуйте далі в open_dialog.
create_supergroup_chat userbot_id, title, опц. is_channel, description create_supergroup_chat / create_supergroup_chat_error Створює нову групу або канал через TDLib createNewSupergroupChat. Якщо is_channel=true, буде створено канал.
get_user userbot_id, user_id get_user / get_user_error Повертає розширений профіль користувача: базові поля user, нормалізований parsed_status/last_seen, profile_photo і full_info.
get_groups_in_common userbot_id, user_id, опц. offset_chat_id, limit (до 100). Alias: get_common_groups. get_groups_in_common / get_groups_in_common_error Повертає спільні групи з користувачем через TDLib getGroupsInCommon. У відповіді є chat_ids[], збагачені items[] з getChat і next_offset_chat_id для пагінації.
get_chat_profile userbot_id, chat_id get_chat_profile / get_chat_profile_error Повертає розширений профіль чату/каналу/групи: chat + chat_full_info, а також supergroup/basic_group (коли доступно), і profile_photo.
set_name userbot_id, first_name, опц. last_name (або full_name/name) set_name / set_name_error Змінює імʼя/прізвище поточного акаунта через TDLib setName.
set_bio userbot_id, bio (або about) set_bio / set_bio_error Оновлює bio (About) поточного акаунта через TDLib setBio. Порожній рядок очищає bio.
set_username userbot_id, username set_username / set_username_error Оновлює @username поточного акаунта через TDLib setUsername. Порожній рядок прибирає username.
set_profile_photo userbot_id, opaque local-upload: photo.key, опц. is_public set_profile_photo / set_profile_photo_error, далі refresh_self_profile Оновлює фото профілю поточного акаунта через TDLib setProfilePhoto. Для нового файлу спочатку виконайте create_tg_media_upload_url, зробіть raw binary PUT і передайте отриманий local-upload: key у photo.key. Backend використає inputFileGenerated + local_file_v1. Після успішної зміни backend робить refresh_self_profile з remote id та поточним URL; новий аватар готується фоновою медіачергою.
set_chat_photo userbot_id, chat_id/channel_id, фото через photo або opaque local-upload: key; опц. file_name. Alias-и: set_group_photo, set_channel_photo. cloud_key більше не підтримується. set_chat_photo / set_chat_photo_error Встановлює статичну або анімовану аватарку групи/каналу через TDLib setChatPhoto. Потрібне право can_change_info.
delete_chat_photo userbot_id, chat_id (або channel_id) delete_chat_photo / delete_chat_photo_error Видаляє поточну аватарку групи/каналу через TDLib setChatPhoto з photo:null. Потрібне ефективне право can_change_info.
set_birthdate userbot_id, day, month, опц. year (або birthdate обʼєкт / null, опц. clear) set_birthdate / set_birthdate_error Оновлює день народження поточного акаунта через TDLib setBirthdate. Якщо рік не передано, використовується 0 (рік прихований). Для очищення дати передайте birthdate: null (або clear: true).
set_chat_title userbot_id, chat_id, title set_chat_title / set_chat_title_error Змінює назву чату/каналу через TDLib setChatTitle.
set_chat_description userbot_id, chat_id, description set_chat_description / set_chat_description_error Змінює опис чату/каналу через TDLib setChatDescription.
set_chat_permissions userbot_id, chat_id, permissions set_chat_permissions / set_chat_permissions_error Змінює загальні дозволи учасників чату через TDLib setChatPermissions. Підтримує частковий payload і alias полів (can_send_messages, can_add_web_page_previews, can_manage_topics).
add_chat_member_permission_exception userbot_id, chat_id, user_id, permissions, опц. restricted_until_date add_chat_member_permission_exception / add_chat_member_permission_exception_error Створює персональний виняток прав учасника через chatMemberStatusRestricted. Часткові permissions накладаються на стандартні права групи. Alias: create_chat_member_permission_exception.
edit_chat_member_permission_exception userbot_id, chat_id, user_id, часткові permissions, опц. restricted_until_date edit_chat_member_permission_exception / edit_chat_member_permission_exception_error Редагує наявний персональний виняток, зберігаючи permissions, які не передані. Alias: update_chat_member_permission_exception.
delete_chat_member_permission_exception userbot_id, chat_id, user_id delete_chat_member_permission_exception / delete_chat_member_permission_exception_error Видаляє персональний виняток і повертає учаснику статус chatMemberStatusMember, після чого діють стандартні права групи.
check_chat_username userbot_id, chat_id, username check_chat_username / check_chat_username_error Перевіряє username для чату/каналу через TDLib checkChatUsername.
set_supergroup_username userbot_id, chat_id (або supergroup_id), username set_supergroup_username / set_supergroup_username_error Змінює @username каналу/супергрупи через TDLib setSupergroupUsername. Порожній рядок робить чат приватним.
toggle_chat_has_protected_content userbot_id, chat_id, has_protected_content toggle_chat_has_protected_content / toggle_chat_has_protected_content_error Вмикає/вимикає захист контенту (копіювання/пересилання) через TDLib toggleChatHasProtectedContent.
set_chat_slow_mode_delay userbot_id, chat_id, slow_mode_delay (або delay) set_chat_slow_mode_delay / set_chat_slow_mode_delay_error Керує “повільним режимом” у чаті через TDLib setChatSlowModeDelay. 0 вимикає slow mode.
set_chat_direct_messages_group userbot_id, chat_id, is_enabled, опц. paid_message_star_count (або star_count) set_chat_direct_messages_group / set_chat_direct_messages_group_error Керує блоком “Приймати повідомлення” в каналі через TDLib setChatDirectMessagesGroup: вмикає/вимикає прийом повідомлень і задає ціну в Stars за повідомлення.
set_chat_discussion_group userbot_id, chat_id, discussion_chat_id set_chat_discussion_group / set_chat_discussion_group_error Прив’язує або відв’язує групу обговорення каналу через TDLib setChatDiscussionGroup. Для відв’язки передайте discussion_chat_id=0.
get_suitable_discussion_chats userbot_id get_suitable_discussion_chats / get_suitable_discussion_chats_error Повертає список чатів, які підходять для прив’язки як група обговорення, через TDLib getSuitableDiscussionChats.
get_suitable_personal_chats userbot_id get_suitable_personal_chats / get_suitable_personal_chats_error Повертає список каналів, які можна вибрати як “особистий канал”, через TDLib getSuitablePersonalChats.
set_personal_chat userbot_id, chat_id set_personal_chat / set_personal_chat_error Встановлює канал як “особистий канал” через TDLib setPersonalChat. У відповіді додається item, зібраний через build_chat_item.
hide_personal_chat userbot_id hide_personal_chat / hide_personal_chat_error Приховує “особистий канал” через TDLib setPersonalChat з chat_id=0.
get_chat_members userbot_id, chat_id, опц. limit, offset, query, filter/member_filter get_chat_members / get_chat_members_error Повертає учасників чату з пагінацією. Кожен user-учасник містить username без @ (або null), boolean is_bot, is_verified та is_premium. Username береться з актуального usernames.active_usernames із fallback на legacy-поле. Ці самі ознаки доступні в sender повідомлення, reaction senders і повному профілі get_user. Для filter:"blocked" у member_status додає blocked_by, blocked_by_user_id, blocked_by_chat_id, blocked_at, якщо дані є в admin log.
import_contacts userbot_id і одне з: phone або contact_user_id/user_id/tg_user_id; опц. first_name, last_name, vcard, share_phone_number import_contacts / import_contacts_error З номером використовує importContacts; без номера додає відомого Telegram-користувача через addContact. Якщо last_name не передано, може використовуватись поточне значення; явний last_name: "" очищає прізвище. Повертає requested_contact і contacts[].
block_user userbot_id, user_id (або tg_user_id), опц. is_blocked, block_list block_user / block_user_error Блокує або розблоковує користувача через TDLib setMessageSenderBlockList.
unblock_user userbot_id, user_id (або tg_user_id) unblock_user / unblock_user_error Видаляє користувача зі списку блокування через TDLib setMessageSenderBlockList з block_list=null.
get_blocked_users userbot_id, опц. block_list, offset, limit get_blocked_users / get_blocked_users_error Повертає список заблокованих sender-ів через TDLib getBlockedMessageSenders з окремими масивами users і chats.
get_privacy_setting userbot_id, setting (або privacy_setting) get_privacy_setting / get_privacy_setting_error Повертає поточні правила приватності для одного налаштування. Для user rules використовує TDLib getUserPrivacySettingRules, для “Повідомлення” — getNewChatPrivacySettings.
get_privacy_settings userbot_id, опц. settings[] або CSV-рядок get_privacy_settings / get_privacy_settings_error Повертає набір privacy-налаштувань одним запитом (масив items + errors).
set_privacy_setting userbot_id, setting, опц. mode, allow_user_ids/always_allow_user_ids, restrict_user_ids/never_allow_user_ids, allow_chat_ids, restrict_chat_ids, allow_premium_users, rules, allow_new_chats_from_unknown_users set_privacy_setting / set_privacy_setting_error Змінює privacy-правила. Підтримує базові режими (all/contacts/nobody) і винятки для користувачів/чатів, або повний масив TDLib rules.
add_chat_member userbot_id, chat_id, user_id (або tg_user_id), опц. forward_limit add_chat_member / add_chat_member_error Додає користувача через TDLib addChatMember. Результат — failedToAddMembers, як і для множинного запрошення; транспортний успіх не означає, що користувача додано. Для груп підтримується forward_limit.
add_chat_members userbot_id, chat_id, user_ids[] (або userids[]) add_chat_members / add_chat_members_error Додає кількох користувачів через TDLib addChatMembers одним запитом. Результат — native failedToAddMembers; непорожній failed_to_add_members означає, що зазначених користувачів не додано. Поле count не повертається.
remove_chat_member userbot_id, chat_id, user_id (або tg_user_id), опц. revoke_messages remove_chat_member / remove_chat_member_error Вилучає користувача з каналу/чату через TDLib setChatMemberStatus зі статусом chatMemberStatusBanned.
restore_chat_member userbot_id, chat_id, user_id (або tg_user_id) restore_chat_member / restore_chat_member_error Відновлює користувачу можливість знову приєднатись (unban) через TDLib setChatMemberStatus зі статусом chatMemberStatusLeft. Не додає назад автоматично.
add_chat_administrator userbot_id, chat_id, user_id (або tg_user_id), опц. custom_title, rights, is_anonymous, can_be_edited add_chat_administrator / add_chat_administrator_error Призначає користувача адміністратором у каналі/групі через TDLib setChatMemberStatus з chatMemberStatusAdministrator.
remove_chat_administrator userbot_id, chat_id, user_id (або tg_user_id) remove_chat_administrator / remove_chat_administrator_error Знімає адмінські права і повертає користувача до звичайного member через TDLib setChatMemberStatus з chatMemberStatusMember.
create_chat_member_tag / set_chat_member_tag userbot_id, chat_id, user_id (або tg_user_id), tag (або custom_title) Назва action / відповідний _error Створює кастомний тег адміністратора. set_chat_member_tag також редагує наявний тег.
edit_chat_member_tag / set_chat_administrator_custom_title userbot_id, chat_id, user_id, tag (або custom_title) Назва action / відповідний _error Редагує кастомний тег адміністратора зі збереженням поточних прав та анонімності.
delete_chat_member_tag userbot_id, chat_id, user_id (або tg_user_id) delete_chat_member_tag / delete_chat_member_tag_error Видаляє кастомний тег адміністратора без зміни його прав.
transfer_chat_ownership userbot_id, chat_id, user_id (або tg_user_id), password (або current_password) transfer_chat_ownership / transfer_chat_ownership_error Передає право власника каналу/групи іншому адміністратору через TDLib transferChatOwnership. Потрібен пароль 2FA поточного власника.
get_password_state userbot_id get_password_state / get_password_state_error Повертає стан 2FA через TDLib getPasswordState: чи увімкнений пароль, password_hint, стан recovery email.
request_2fa_password_recovery userbot_id request_2fa_password_recovery / request_2fa_password_recovery_error Запускає recovery 2FA-пароля. Якщо recovery email прив'язаний, TDLib надсилає код на пошту; якщо пошти немає або 2FA не увімкнений, повертається помилка. Старий alias request_password_recovery теж підтримується.
check_password_recovery_code userbot_id, recovery_code check_password_recovery_code / check_password_recovery_code_error Перевіряє recovery-код, який користувач отримав на пошту після request_2fa_password_recovery.
recover_password userbot_id, recovery_code, опц. new_password, new_hint recover_password / recover_password_error Підтверджує recovery-код і завершує відновлення 2FA-пароля через TDLib recoverPassword.
verify_2fa_password userbot_id, password (або current_password) verify_2fa_password / verify_2fa_password_error Перевіряє валідність поточного 2FA-пароля через TDLib getRecoveryEmailAddress (без зміни налаштувань).
change_2fa_password userbot_id, current_password (або old_password/password), new_password, опц. new_hint, set_recovery_email_address, new_recovery_email_address change_2fa_password / change_2fa_password_error Змінює 2FA-пароль через TDLib setPassword. Повертає оновлений password_state.
disable_2fa_password userbot_id, current_password (або password) disable_2fa_password / disable_2fa_password_error Вимикає 2FA-пароль через TDLib setPassword з порожнім new_password.
change_2fa_recovery_email userbot_id, current_password (або password), new_recovery_email_address (або recovery_email_address/email) change_2fa_recovery_email / change_2fa_recovery_email_error Змінює recovery email для 2FA через TDLib setRecoveryEmailAddress. Якщо пошта нова, потрібне підтвердження на email.
get_transfer_ownership_state userbot_id get_transfer_ownership_state / get_transfer_ownership_state_error Об’єднує перевірки TDLib getPasswordState і canTransferOwnership в один запит для UI блоку перевірки безпеки.
toggle_supergroup_sign_messages userbot_id, chat_id (або supergroup_id), sign_messages, опц. show_message_sender toggle_supergroup_sign_messages / toggle_supergroup_sign_messages_error Перемикає підпис повідомлень у каналі/супергрупі через TDLib toggleSupergroupSignMessages. Якщо show_message_sender не передано, бекенд збереже поточне значення.
toggle_supergroup_is_all_history_available userbot_id, chat_id (або supergroup_id), is_all_history_available toggle_supergroup_is_all_history_available / toggle_supergroup_is_all_history_available_error Керує видимістю старої історії для нових учасників у супергрупі через TDLib toggleSupergroupIsAllHistoryAvailable.
toggle_supergroup_has_hidden_members userbot_id, chat_id (або supergroup_id), has_hidden_members toggle_supergroup_has_hidden_members / toggle_supergroup_has_hidden_members_error Приховує (true) або показує (false) список учасників супергрупи через TDLib toggleSupergroupHasHiddenMembers. Потрібні відповідні права Telegram; результат містить фактичний стан has_hidden_members.
toggle_supergroup_is_forum userbot_id, chat_id (або supergroup_id), is_forum toggle_supergroup_is_forum / toggle_supergroup_is_forum_error Вмикає/вимикає режим гілок (forum topics) у супергрупі через TDLib toggleSupergroupIsForum.
check_chat_invite_link userbot_id, invite_link (або link/url) check_chat_invite_link / check_chat_invite_link_error Перевіряє Telegram-лінк чату. Для invite links використовує TDLib checkChatInviteLink; якщо chat_id уже відомий, бек додатково звіряє актуальну публічність через свіжий getChat. Якщо відповідь застаріла або без chat_id, бек робить best-effort refresh через searchChatsOnServer за exact title. Для публічних t.me/username або @username резолвить чат через searchPublicChat. Якщо chat_id усе одно недоступний, у відповіді повертається chat_id_unavailable_reason.
join_chat_by_invite_link userbot_id, invite_link (або link/url) join_chat_by_invite_link / join_chat_by_invite_link_error Приєднує поточного користувача до чату за Telegram-посиланням. Для invite links використовує TDLib joinChatByInviteLink, для публічних t.me/username лінків резолвить чат і викликає joinChat. У відповіді повертає joined, join_request_sent, а також chat і item, якщо чат уже доступний.
join_chat userbot_id, chat_id join_chat / join_chat_error Приєднує поточного користувача до вже відомого чату через TDLib joinChat. У відповіді є joined, join_request_sent, chat та item, якщо чат доступний.
get_chat_invite_links userbot_id, chat_id, опц. creator_user_id, is_revoked, offset_date, offset_invite_link, limit get_chat_invite_links / get_chat_invite_links_error Повертає список запрошувальних посилань через TDLib getChatInviteLinks. Якщо creator_user_id не передано, бекенд підставляє поточного користувача через getMe.
create_chat_invite_link userbot_id, chat_id, опц. name, expiration_date, member_limit, creates_join_request create_chat_invite_link / create_chat_invite_link_error Створює нове invite link через TDLib createChatInviteLink.
create_chat_subscription_invite_link userbot_id, chat_id, опц. name, subscription_pricing (або subscription_period + subscription_star_count) create_chat_subscription_invite_link / create_chat_subscription_invite_link_error Створює платне invite link через TDLib createChatSubscriptionInviteLink (Stars subscription для каналу).
edit_chat_subscription_invite_link userbot_id, chat_id, invite_link, опц. name edit_chat_subscription_invite_link / edit_chat_subscription_invite_link_error Редагує платне invite link через TDLib editChatSubscriptionInviteLink (назва посилання).
edit_chat_invite_link userbot_id, chat_id, invite_link, опц. name, expiration_date, member_limit, creates_join_request edit_chat_invite_link / edit_chat_invite_link_error Редагує invite link через TDLib editChatInviteLink.
revoke_chat_invite_link userbot_id, chat_id, invite_link revoke_chat_invite_link / revoke_chat_invite_link_error Відкликає invite link через TDLib revokeChatInviteLink.
replace_primary_chat_invite_link userbot_id, chat_id replace_primary_chat_invite_link / replace_primary_chat_invite_link_error Генерує нове primary invite link через TDLib replacePrimaryChatInviteLink.
delete_revoked_chat_invite_link userbot_id, chat_id, invite_link delete_revoked_chat_invite_link / delete_revoked_chat_invite_link_error Видаляє відкликане invite link зі списку через TDLib deleteRevokedChatInviteLink (якщо підтримується версією TDLib).
delete_all_revoked_chat_invite_links userbot_id, chat_id, опц. creator_user_id delete_all_revoked_chat_invite_links / delete_all_revoked_chat_invite_links_error Видаляє всі відкликані invite links для одного адміністратора через TDLib deleteAllRevokedChatInviteLinks. Якщо creator_user_id не передано, бекенд підставляє поточного користувача через getMe.
get_chat_join_requests userbot_id, chat_id, опц. invite_link, query, offset_request, limit get_chat_join_requests / get_chat_join_requests_error Повертає запити на вступ через TDLib getChatJoinRequests. Для пагінації можна передавати останній елемент як offset_request.
get_chat_invite_link_members userbot_id, chat_id, invite_link, опц. only_with_expired_subscription, offset_member, limit get_chat_invite_link_members / get_chat_invite_link_members_error Повертає користувачів, які приєдналися за конкретним invite link, через TDLib getChatInviteLinkMembers. Для пагінації можна передавати останній елемент як offset_member.
process_chat_join_request userbot_id, chat_id, user_id (або tg_user_id), опц. approve process_chat_join_request / process_chat_join_request_error Схвалює або відхиляє запит на вступ через TDLib processChatJoinRequest.
process_chat_join_requests userbot_id, chat_id, опц. invite_link, approve process_chat_join_requests / process_chat_join_requests_error Схвалює або відхиляє всі заявки (або всі заявки конкретного invite link) через TDLib processChatJoinRequests.

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

{"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}

Автоматична міграція basic group. Команди set_chat_slow_mode_delay, set_supergroup_username, toggle_supergroup_is_all_history_available, toggle_supergroup_is_forum, toggle_supergroup_has_hidden_members та toggle_supergroup_sign_messages спочатку мігрують basic group через upgradeBasicGroupChatToSupergroupChat, а потім застосовують налаштування до отриманої супергрупи. Міграція незворотна та потребує прав власника. Після міграції result.chat_id і result.supergroup_id містять нові ID; client_request_id зберігається. Фронтенд має переключити діалог на новий chat_id. Якщо налаштування завершилось помилкою після успішної міграції, нові ID також повертаються в result події <action>_error. Якщо сама міграція не вдалась, налаштування не виконується. Оновлення списку передають basic_group.is_active та basic_group.upgraded_to_supergroup_id для старої групи.

{"type":"set_chat_slow_mode_delay","userbot_id":183,"client_request_id":"slow-mode-123","result":{"@type":"ok","chat_id":"-1004383579256","supergroup_id":4383579256,"slow_mode_delay":30,"is_disabled":false}}
{"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.

ПолеЩо дозволяєЩо робити на фронті
can_send_basic_messages Надсилання тексту. Блокувати composer (text input + send).
can_send_photos Надсилання фото. Вимикати кнопку фото/галереї.
can_send_videos Надсилання відео. Вимикати кнопку відео.
can_send_audios Надсилання аудіо/музики. Вимикати кнопку audio upload.
can_send_voice_notes Надсилання voice messages. Ховати/блокувати мікрофон.
can_send_video_notes Надсилання video notes (round video). Ховати/блокувати кнопку video note.
can_send_documents Надсилання файлів/документів. Вимикати file picker.
can_send_polls Створення опитувань. Ховати кнопку poll.
can_send_other_messages GIF/sticker/animated emoji/інші не-текстові типи. Вимикати sticker/GIF/premium reactions composer entry.
can_add_link_previews Увімкнення превʼю посилань у повідомленнях. Вимикати toggle «show link preview».
can_change_info Редагування назви/опису/аватара чату. Показувати/ховати кнопку edit chat profile.
can_invite_users Запрошення користувачів у чат. Показувати/ховати invite member.
can_pin_messages Закріплення повідомлень. Блокувати action pin_message.
can_create_topics Створення тем у forum/supergroup. Показувати/ховати create topic.

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

ПолеЩо означаєВплив на фронт
supergroup.join_to_send_messages Для каналу треба приєднатись, щоб писати. Показати CTA «Join to send messages» замість composer.
supergroup.is_channel Це канал, а не група. Використовувати channel UI (read-only для звичайного підписника).
has_protected_content Контент захищено від пересилання/копіювання. Обмежити forward/save actions у UI.
notification_settings.mute_for Тривалість mute у секундах. Стан toggle mute та label «muted until ...».

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

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

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

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

ПолеОписЩо робити на фронті
@typeТип обʼєкта. Для чату завжди chat.Використовувати для type guard.
idУнікальний ID чату.Ключ чату в сторі, роутингу та WS-командах.
typeВкладений тип чату (chatTypeSupergroup/chatTypePrivate тощо).Перемикати шаблон UI за типом чату.
titleНазва чату.Показувати в header, списку чатів, breadcrumbs.
accent_color_idTelegram accent color для чату.Опціонально стилізувати avatar ring/title badge.
background_custom_emoji_idID custom emoji для background чату, "0" якщо відсутній.Якщо не "0" - завантажувати відповідний decoration.
profile_accent_color_idAccent color профілю чату, -1 якщо дефолт.Використовувати fallback, якщо значення -1.
profile_background_custom_emoji_idCustom emoji для background профілю, "0" якщо відсутній.Якщо є emoji-id, показувати в profile header.
permissionsБазові права учасника в чаті.Блокувати/дозволяти дії composer/admin UI.
positionsПозиції чату в різних списках з порядком сортування.Використовувати для порядку чатів у sidebar.
chat_listsСписки, де присутній чат (main, archive, folders).Показувати badges folder/main/archive.
message_sender_idПоточний sender від імені якого пише користувач у чаті.Відображати від чийого імені йде відправка.
has_protected_contentКонтент захищений від пересилання/копіювання.Вимикати forward/save/copy там, де потрібно.
is_translatableЧи підтримується переклад повідомлень чату.Показувати/ховати кнопку translate.
is_marked_as_unreadЧат позначено як непрочитаний вручну.Показувати unread marker навіть без нових меседжів.
view_as_topicsUI режим показу як список тем.Відкривати чат у режимі topics list.
has_scheduled_messagesЄ заплановані повідомлення.Показувати індикатор/вхід у scheduled messages.
can_be_deleted_only_for_selfЧат можна видалити тільки локально для себе.Текст підтвердження delete адаптувати під local-only.
can_be_deleted_for_all_usersЧат можна видалити для всіх (залежить від типу чату і прав).Дозволяти опцію "delete for all", якщо true.
can_be_reportedЧат доступний для скарги.Показувати action report.
default_disable_notificationДефолт надсилання без звуку в цей чат.Початковий стан toggle silent send.
unread_countКількість непрочитаних повідомлень.Badge непрочитаних у списку чатів.
last_read_inbox_message_idОстанній прочитаний вхідний message ID.Обчислення read markers по вхідним.
last_read_outbox_message_idОстанній прочитаний вихідний message ID.Обчислення read markers по вихідним.
unread_mention_countКількість непрочитаних згадок.Показувати mention-badge окремо від unread_count.
unread_reaction_countКількість непрочитаних реакцій.Показувати reaction badge.
notification_settingsПерсональні налаштування нотифікацій для цього чату.Ініціалізація екрана chat notifications.
available_reactionsПолітика доступних реакцій у чаті.Обмежувати reaction picker.
message_auto_delete_timeTTL автознищення повідомлень у секундах, 0 = вимкнено.Показувати current auto-delete value.
theme_nameТема чату (якщо застосовується).Опційно стилізувати чат або ігнорувати пусте значення.
reply_markup_message_idID повідомлення з активним reply markup.Трекати pinned keyboard / interactive markup state.
client_dataСлужбове client-side поле TDLib.Зазвичай не використовується у фронті.
profile_photoФото чату з розмірами.Avatar rendering + вибір оптимального size.
chat_full_infoДетальна інфа чату (в цьому payload порожній обʼєкт).Перевіряти на пустий обʼєкт перед рендером деталізації.
supergroupКоротка інфа супергрупи/каналу.Визначення типу, режиму, membership та forum-стану.
supergroup_full_infoРозширена інфа супергрупи.Рендер блоку About/Permissions/Statistics/Commands.
basic_groupОбʼєкт basic group, якщо чат цього типу.Для supergroup буде null, використовувати тільки для basic groups.
basic_group_full_infoРозширена інфа basic group.Для supergroup буде null.

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

ПолеОписПоточне значенняВплив на UI
can_send_basic_messagesДозвіл надсилати текстові повідомлення.trueComposer активний.
can_send_audiosДозвіл надсилати аудіофайли.trueAudio upload доступний.
can_send_documentsДозвіл надсилати документи/файли.trueFile picker доступний.
can_send_photosДозвіл надсилати фото.truePhoto upload доступний.
can_send_videosДозвіл надсилати відео.trueVideo upload доступний.
can_send_video_notesДозвіл надсилати video notes.trueVideo note action доступний.
can_send_voice_notesДозвіл надсилати voice notes.trueМікрофон доступний.
can_send_pollsДозвіл створювати опитування.truePoll action доступний.
can_send_other_messagesДозвіл надсилати sticker/GIF/інші типи.trueSticker/GIF picker доступний.
can_add_link_previewsДозвіл додавати preview до URL.trueToggle preview доступний.
can_change_infoДозвіл редагувати назву/опис/аватар.falseEdit chat profile прихований.
can_invite_usersДозвіл запрошувати нових учасників.trueInvite member доступний.
can_pin_messagesДозвіл закріплювати повідомлення.falsePin message action заблокований.
can_create_topicsДозвіл створювати нові теми.falseCreate topic action заблокований.

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

ПолеОписПоточне значення
positions[0].@typeТип елемента позиції.chatPosition
positions[0].list.@typeСписок, для якого задана позиція.chatListMain
positions[0].orderПорядок сортування (рядок-число)."7608161469645737115"
positions[0].is_pinnedЧи закріплено чат у цьому списку.false
chat_lists[0]Належність до folder з ID 22.{"@type":"chatListFolder","chat_folder_id":22}
chat_lists[1]Належність до folder з ID 97.{"@type":"chatListFolder","chat_folder_id":97}
chat_lists[2]Належність до основного списку.{"@type":"chatListMain"}

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

ПолеОписПоточне значенняВплив на UI
use_default_mute_forВикористовувати глобальний mute.falseПоказувати, що застосовано локальний mute.
mute_forMute duration в секундах.376070182Показувати чат як muted.
use_default_soundВикористовувати глобальний звук.trueLocal sound picker можна ховати/дизейблити.
sound_idID локального sound."-1"Зазвичай дефолтний звук.
use_default_show_previewВикористовувати глобальний show preview.truePreview toggle наслідує global state.
show_previewЛокальний прапорець preview.falseПрацює лише якщо use_default_show_preview=false.
use_default_mute_storiesВикористовувати глобальний mute stories.trueStories mute контролюється глобальним налаштуванням.
mute_storiesЛокальний mute для stories.falseПрацює лише при use_default_mute_stories=false.
use_default_story_soundВикористовувати глобальний звук stories.trueStory sound picker наслідує глобальний.
story_sound_idID звуку stories."-1"Дефолтний story sound.
use_default_show_story_senderВикористовувати глобальне відображення автора story.trueStory sender visibility наслідує global.
show_story_senderЛокальний прапорець показу автора story.trueПрацює лише якщо use_default_show_story_sender=false.
use_default_disable_pinned_message_notificationsВикористовувати глобальне правило для pinned notifications.trueЛокальний toggle pinned notifications наслідує global.
disable_pinned_message_notificationsВимкнення нотифікацій про pin.falseАктивний лише якщо use_default...=false.
use_default_disable_mention_notificationsВикористовувати глобальне правило для mention notifications.trueMention notifications наслідують global.
disable_mention_notificationsВимкнення нотифікацій про згадки.falseАктивний лише якщо use_default...=false.

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

ПолеОписПоточне значення
available_reactions.@typeРежим доступних реакцій.chatAvailableReactionsAll
available_reactions.max_reaction_countМаксимум реакцій на повідомлення.11
profile_photo.typeТип обʼєкта фото профілю.profilePhoto
profile_photo.file_idБазовий file_id фото.4390
profile_photo.widthБазова ширина.160
profile_photo.heightБазова висота.160
profile_photo.sizes[0]Size variant a.{"file_id":4390,"type":"a","width":160,"height":160}
profile_photo.sizes[1]Size variant b.{"file_id":4391,"type":"b","width":320,"height":320}
profile_photo.sizes[2]Size variant c.{"file_id":4392,"type":"c","width":640,"height":640}

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

ПолеОписПоточне значенняВплив на UI
@typeТип обʼєкта супергрупи.supergroupType guard.
idID супергрупи.1987658875Використовувати у TDLib методах супергрупи.
usernames.@typeТип обʼєкта usernames.usernamesType guard.
usernames.active_usernamesАктивні username.["romaniaitcommunity"]Показати public links.
usernames.disabled_usernamesВимкнені username.[]Зазвичай не показувати в публічному UI.
usernames.editable_usernameUsername, який можна редагувати власнику/адміну."romaniaitcommunity"В admin UI ставити в поле editable username.
dateUnix timestamp створення/міграції сутності.1755500986Опційно показувати "created at".
status.@typeСтатус поточного користувача в чаті.chatMemberStatusMemberРоль користувача = member.
status.member_until_dateДо якої дати діє статус (0 = без обмеження).0Не показувати timeout membership.
member_countКількість учасників.2048Показати counter.
boost_levelПоточний boost level.0Показати/сховати boost badge.
has_linked_chatЧи має повʼязаний чат.falseLinked chat section приховати.
has_locationЧи має група геолокацію.falseLocation section приховати.
sign_messagesПідпис повідомлень у чаті.trueПоказувати автора/підпис у повідомленнях.
show_message_senderПоказувати sender у постах.trueВідображати sender line у message cell.
join_to_send_messagesПотрібно вступити, щоб писати.trueЯкщо юзер не member - CTA Join замість composer.
join_by_requestВступ тільки через заявку.falseКнопка Join без flow заявки.
is_slow_mode_enabledЧи активний slow mode.falseSlow mode timer приховати.
is_channelОзнака каналу.falseЦе група, не канал.
is_broadcast_groupОзнака broadcast-group.falseСтандартний груповий UI.
is_forumОзнака форуму з темами.trueВідкривати screen тем, підтримувати message_thread_id.
has_sensitive_contentКонтент 18+/sensitive.falseБез додаткових content warnings.
restriction_reasonПричина обмеження контенту.""Порожньо - не показувати restriction alert.
has_active_storiesЄ активні stories.falseStories ring не показувати.
has_unread_active_storiesЄ непрочитані stories.falseStories unread badge не показувати.

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

ПолеОписПоточне значенняВплив на UI
@typeТип обʼєкта.supergroupFullInfoType guard.
descriptionОпис чату.""About-блок порожній.
member_countКількість учасників.2048Показати в header/about.
administrator_countКількість адміністраторів.0Admin count = 0 або приховати.
restricted_countКількість restricted users.0Moderation counters.
banned_countКількість забанених.0Moderation counters.
linked_chat_idID повʼязаного чату.0Linked chat section приховати.
slow_mode_delayІнтервал slow mode (сек).0Slow mode неактивний.
slow_mode_delay_expires_inЗалишок таймера slow mode.0.0Timer не показувати.
can_enable_paid_reactionЧи можна увімкнути paid reactions.falsePaid reactions toggle заблокований.
can_get_membersЧи можна отримати список учасників.trueMembers tab доступний.
has_hidden_membersЧи прихований список учасників.trueПоказати обмеження видимості member list.
can_hide_membersЧи можна керувати приховуванням members.falseAdmin control hide members недоступний.
can_set_sticker_setЧи можна встановити sticker set.falseSticker set editor недоступний.
can_set_locationЧи можна встановити geolocation.falseLocation editor недоступний.
can_get_statisticsЧи доступна статистика чату.falseStatistics screen приховати.
can_get_revenue_statisticsЧи доступна revenue статистика.falseRevenue section приховати.
can_get_star_revenue_statisticsЧи доступна Star revenue статистика.falseStar revenue section приховати.
can_toggle_aggressive_anti_spamЧи можна керувати aggressive anti-spam.falseAnti-spam toggle недоступний.
is_all_history_availableЧи доступна вся історія новим учасникам.trueПоказати в about як відкриту історію.
can_have_sponsored_messagesЧи можуть бути sponsored messages.trueПідтримувати sponsored marker у future UI.
has_aggressive_anti_spam_enabledФактичний стан aggressive anti-spam.falseAnti-spam status = off.
has_paid_media_allowedЧи дозволений paid media.falsePaid media composer actions вимкнені.
has_pinned_storiesЧи є pinned stories.falsePinned stories block приховати.
my_boost_countСкільки бустів користувач дав чату.0Boost contribution badge = 0.
unrestrict_boost_countСкільки бустів треба для зняття обмежень.0Restriction boost hint не потрібен.
sticker_set_idID sticker set чату."0"Sticker set не заданий.
custom_emoji_sticker_set_idID custom emoji sticker set."0"Custom emoji set не заданий.
bot_commandsСписок команд ботів у чаті.[{"@type":"botCommands","bot_user_id":313092884,"commands":[{"@type":"botCommand","command":"help","description":"Get list of commands"}]}]Заповнювати slash command hints/autocomplete.
upgraded_from_basic_group_idID basic group, з якої мігрували.0Міграції не було.
upgraded_from_max_message_idМаксимальний msg id на момент міграції.0Міграції не було.

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

ПолеОписПоточне значення
bot_commands[0].@typeТип контейнера команд бота.botCommands
bot_commands[0].bot_user_idUser ID бота, якому належать команди.313092884
bot_commands[0].commands[0].@typeТип обʼєкта команди.botCommand
bot_commands[0].commands[0].commandSlash-команда."help"
bot_commands[0].commands[0].descriptionОпис команди."Get list of 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 (повністю)

ПолеОписПоточне значенняВплив на фронт
type.is_channelОзнака, що це канал.trueВмикати channel-логіку і read-only composer для неадміна.
view_as_topicsРежим тем у чаті.falseВідкривати звичайну стрічку, не список топіків.
permissionsПрава поточного учасника.усі falseПовністю заблокований composer/action send.
positions[0].list.@typeОсновний список для сортування.chatListMainПозиція в головному списку чатів.
chat_listsНалежність до списків/папок.folder 97 + mainПоказувати badge папки і main.
unread_countНепрочитані повідомлення.45Badge unread.
unread_mention_countНепрочитані згадки.0Mention badge відсутній.
unread_reaction_countНепрочитані реакції.0Reaction badge відсутній.
notification_settings.mute_forЛокальний mute у секундах.376071013Чат має стан muted.
available_reactions.@typeРежим реакцій.chatAvailableReactionsSomeПоказувати тільки whitelist реакцій.
available_reactions.max_reaction_countМаксимум реакцій на меседж.4Обмежити reaction picker.
has_protected_contentЗахист від копіювання/forward.falseForward/save не блокувати цим прапорцем.
profile_photoФото каналу.file_id 4158 + sizesВибирати size за DPI/контейнером.
chat_full_infoДетальний обʼєкт chat.{}Перевіряти на порожній обʼєкт перед рендером.

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

ПолеПоточне значенняЩо це означає у UI
can_send_basic_messagesfalseText composer вимкнений.
can_send_audiosfalseAudio upload вимкнений.
can_send_documentsfalseFile upload вимкнений.
can_send_photosfalsePhoto upload вимкнений.
can_send_videosfalseVideo upload вимкнений.
can_send_video_notesfalseVideo notes вимкнені.
can_send_voice_notesfalseMic/voice вимкнений.
can_send_pollsfalseCreate poll вимкнений.
can_send_other_messagesfalseGIF/sticker/emoji media вимкнені.
can_add_link_previewsfalseLink preview toggle вимкнений.
can_change_infofalseEdit profile channel hidden/disabled.
can_invite_usersfalseInvite UI hidden/disabled.
can_pin_messagesfalsePin action hidden/disabled.
can_create_topicsfalseCreate topic hidden/disabled (канал без тем).

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

ПолеПоточне значенняВплив на фронт
is_channeltrueКанал, не група.
is_forumfalseРежим тем не використовувати.
member_count11696Показувати subscriber count.
boost_level2Показувати boost badge.
has_linked_chattrueПоказувати блок linked chat.
sign_messagesfalseАвтор постів як підпис не показується.
show_message_senderfalseSender line у пості не показувати.
join_to_send_messagestrueДля non-member показати CTA Join.
join_by_requestfalseJoin без заявки.
is_slow_mode_enabledfalseSlow mode індикатор не показувати.
has_sensitive_contentfalseБез sensitive warning.
restriction_reason""Restriction banner не показувати.
has_active_storiesfalseStories ring не показувати.
has_unread_active_storiesfalseStories unread badge не показувати.

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

ПолеПоточне значенняВплив на фронт
descriptionнепорожній текст + посиланняРендерити multi-line about з активними URL.
linked_chat_id-1002435456208Кнопка "Discuss" / перехід у linked chat.
can_get_membersfalseMembers list/tab недоступний.
has_hidden_memberstrueПоказати, що список підписників приховано.
can_enable_paid_reactiontrueAdmin toggle paid reactions може бути доступний.
has_paid_media_allowedtruePaid media можливий у цьому каналі.
has_pinned_storiestrueПоказувати блок pinned stories.
is_all_history_availabletrueВся історія доступна.
can_have_sponsored_messagestrueПідтримувати маркер sponsored posts.
bot_commands[]Slash-command hints не показувати.
can_get_statisticsfalseStatistics розділ приховати.
can_get_revenue_statisticsfalseRevenue statistics приховати.
can_get_star_revenue_statisticsfalseStar revenue statistics приховати.
can_toggle_aggressive_anti_spamfalseAnti-spam toggle недоступний.
sticker_set_id"0"Sticker set не налаштований.
custom_emoji_sticker_set_id"0"Custom emoji set не налаштований.

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

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

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

ПолеПоточне значенняЩо це означає для фронту
type.@typechatTypeBasicGroupРендерити group UI, не channel і не forum.
type.basic_group_id232048874Використовувати для базових group-операцій.
positions[]Позиція може братися з chat_lists/локального сортування.
chat_listsfolder 22 + mainПоказувати належність до папки і main list.
profile_photonullПоказувати fallback avatar з ініціалами.
supergroupnullSupergroup-поля не використовувати.
basic_groupobjectОсновне джерело статусу/типу участі в basic group.
basic_group_full_infoobjectДжерело members/invite link/creator info.
can_be_deleted_only_for_selftrueУ delete-dialog показати локальне видалення як доступне.
can_be_deleted_for_all_userstrueПоказати "delete for all users" як доступну дію (якщо UX це підтримує).
can_be_reportedfalseAction report приховати.

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

ПолеПоточне значенняВплив на UI
can_send_basic_messagestrueText composer активний.
can_send_audiostrueAudio upload активний.
can_send_documentstrueFile upload активний.
can_send_photostruePhoto upload активний.
can_send_videostrueVideo upload активний.
can_send_video_notestrueVideo notes активні.
can_send_voice_notestrueMic/voice активний.
can_send_pollstrueCreate poll активний.
can_send_other_messagestrueGIF/sticker/emoji media активні.
can_add_link_previewstrueLink preview toggle активний.
can_change_infotrueEdit group info доступний.
can_invite_userstrueInvite users доступний.
can_pin_messagestruePin message доступний.
can_create_topicstrueCreate topic UI можна показувати, якщо функція підтримується в поточній версії.

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

ПолеПоточне значенняВплив на фронт
basic_group.id232048874Груповий ID для карток/кешу.
basic_group.member_count2Показувати member count.
basic_group.status.@typechatMemberStatusCreatorПоточний користувач є creator (адмін максимум).
basic_group.status.custom_title""Кастомний admin title відсутній.
basic_group.status.is_anonymousfalseАнонімний режим адміна вимкнений.
basic_group.status.is_membertrueКористувач є учасником групи.
basic_group.is_activetrueГрупа активна.
basic_group.upgraded_to_supergroup_id0Не мігровано в supergroup.
basic_group_full_info.description""About секція порожня.
basic_group_full_info.creator_user_id410102970Позначити creator у member list.
basic_group_full_info.members2 membersРендер списку учасників з ролями і датами join.
basic_group_full_info.can_hide_membersfalseHide members control недоступний.
basic_group_full_info.can_toggle_aggressive_anti_spamfalseAggressive anti-spam toggle недоступний.
basic_group_full_info.invite_link.invite_linkhttps://t.me/+vCoG9XuaHRs3YTAyПоказати/скопіювати primary invite link.
basic_group_full_info.invite_link.creates_join_requestfalseJoin by direct invite, без заявки.
basic_group_full_info.invite_link.is_primarytrueЦе primary invite link.
basic_group_full_info.invite_link.is_revokedfalseПосилання активне.
basic_group_full_info.bot_commands[]Slash command hints не показувати.

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

Як визначитиЩо дозволити в UIЩо перевіряти додатково
basic_group.status.@type у chatMemberStatusCreator або chatMemberStatusAdministrator Показувати admin tools: edit info, manage members, invite link management, pin messages. Не покладатися лише на permissions; ключова роль - це basic_group.status.
basic_group.status.custom_title непорожній Показувати custom admin badge/title. Fallback на стандартний label "Admin", якщо поле порожнє.
basic_group.status.is_anonymous=true Показувати режим анонімного адміністратора. Пояснити в UI, що повідомлення можуть відправлятись анонімно від групи.
basic_group_full_info.invite_link.is_primary=true Показувати кнопку copy/share primary invite link. Якщо is_revoked=true, ховати copy і пропонувати regenerate.

Важливо: для 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; якщо непрочитаних немає — на першу активну.

ActionПоляПризначення
get_storystory_poster_chat_id, story_id, опц. only_localОтримати конкретну доступну story.
download_storystory_poster_chat_id, story_idОтримати story разом із media_files[]. Для фактичного CDN-завантаження передайте ці файли в існуючий download_files.
get_chat_active_storieschat_idАктивні stories чату, які поточний акаунт може переглянути.
get_chat_archived_storieschat_id, опц. from_story_id, limitАрхів власних/керованих stories; потрібне право edit stories.
get_chat_posted_storieschat_id, опц. from_story_id, limitStories, збережені на сторінці профілю чату.
get_chats_to_post_storiesuserbot_idЧати, від імені яких акаунт може публікувати stories.
can_post_storychat_idПеревірити право і поточні обмеження публікації.
post_storychat_id, content, опц. areas, caption, privacy_settings, album_ids, active_period, from_story_full_id, is_posted_to_chat_page, protect_contentПублікація story через TDLib postStory. content — inputStoryContentPhoto або inputStoryContentVideo. Для нового файлу передавайте opaque local-upload: key: backend створює inputFileGenerated + local_file_v1 і читає файл зі спільного session storage без S3/CDN. Story photo визначається за bytes, декодується, орієнтується, center-crop/resize до TDLib 1080×1920 і передається як RGB JPEG. Сирі URL та conversion="#url#" не підтримуються.
edit_storystory_poster_chat_id, story_id, опц. content, areas, captionРедагування доступної story.
delete_storystory_poster_chat_id, story_idВидалення story.
open_story / close_storystory_poster_chat_id, story_idПозначити story відкритою/закритою; open_story реєструє перегляд у Telegram.
get_story_interactionsstory_id, опц. story_poster_chat_id, offset, limit, filtersПерегляди, реакції, forwards/reposts. Для story каналу передайте story_poster_chat_id.
set_story_privacy_settingsstory_id, privacy_settingsЗміна аудиторії власної story.
set_story_reactionstory_poster_chat_id, story_id, reaction_typeПоставити або прибрати реакцію (null).
reply_to_storystory_poster_chat_id, story_id і payload повідомлення: text/entities або media/media_items, опц. send optionsВідповідає на story через TDLib inputMessageReplyToStory. chat_id можна не передавати: backend використає story_poster_chat_id. Якщо chat_id заданий, він має збігатися з автором story. Telegram не дозволяє відповідати на stories каналів.
toggle_story_is_posted_to_chat_pagestory_poster_chat_id, story_id, is_posted_to_chat_pageЗалишити/прибрати story зі сторінки профілю після завершення.
set_chat_pinned_storieschat_id, story_ids[]Атомарно замінює повний список прикріплених stories через TDLib setChatPinnedStories. Усі stories спочатку мають бути опубліковані на сторінці чату.
pin_story / unpin_storychat_id, story_idЗручний CRUD одного pin: backend читає поточні pinned_story_ids, змінює потрібний ID і записує повний список.
set_chat_active_stories_listchat_id, story_list: main/archive або TDLib objectПереміщує активний story-feed чату між основним списком та архівом через setChatActiveStoriesList.
archive_chat_stories / unarchive_chat_storieschat_idAlias-и для storyListArchive та storyListMain. Це архівування feed конкретного чату, а не примусове завершення власної story.
get_chat_story_albumschat_idПовертає всі story albums чату. Потребує TDLib schema з getChatStoryAlbums; на старій бібліотеці повертає нормалізовану non-retryable capability error.
get_story_album_storieschat_id, story_album_id, опц. offset, limitПовертає stories конкретного альбому з offset-пагінацією.
create_story_albumchat_id, name (1–12 символів), опц. story_ids[]Створює story album і за потреби одразу додає stories.
edit_story_albumchat_id, story_album_id, nameПерейменовує story album через setStoryAlbumName.
delete_story_albumchat_id, story_album_idВидаляє story album.
add_stories_to_story_album / remove_stories_from_story_albumchat_id, story_album_id, story_ids[]Додає stories на початок альбому або видаляє їх з альбому.
reorder_story_album_storieschat_id, story_album_id, story_ids[]Переміщує вказані stories на початок альбому в заданому порядку; решта зберігає поточний порядок.
reorder_story_albumschat_id, story_album_ids[]Задає новий порядок усіх story albums чату.

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

Поле/typeЗначення
inputStoryContentPhotophoto як inputFileId/inputFileRemote, опц. added_sticker_file_ids[].
inputStoryContentVideovideo, duration, опц. cover/animation/sticker поля відповідно до TDLib 1.8.42.
storyPrivacySettingsEveryoneУсі користувачі, з опціональними виключеннями TDLib.
storyPrivacySettingsContactsКонтакти; підтримує списки включень/виключень.
storyPrivacySettingsCloseFriendsТільки Close Friends.
storyPrivacySettingsSelectedUsersТільки явно вибрані користувачі.
inputFileLocalЗаборонений у WebSocket payload з міркувань безпеки; використовуйте inputFileId або inputFileRemote.

Завантаження 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, що й повідомлення, тому окремого завантажувача і дублювання кешу немає.

Native updates: tdlib_updates_v1

У connected та open_client_ready backend оголошує updates_protocol:"tdlib_updates_v1" і chat_list_protocol:"tdlib_chat_list_v3". Це прямий перехід: старих enriched update payload, send-status aliases і автоматичних media downloads для account updates немає. open_dialog, pagination та media-ready залишають свої окремі контракти.

Native update envelope

{"type":"chat_update","userbot_id":550,"payload":{
  "@type":"updateNewMessage","type":"updateNewMessage","userbot_id":550,
  "updates_protocol":"tdlib_updates_v1",
  "message":{"@type":"message","id":"123","chat_id":"-10042",
    "sender_id":{"@type":"messageSenderUser","user_id":"7"},
    "date":1792180292,"content":{"@type":"messageText",
      "text":{"@type":"formattedText","text":"Hello","entities":[]}}}
}}

Подія містить native fields і transport metadata. IDs — рядки; date/edit_date/counts — числа. Null зберігається для очищення стану. File reference містить id, remote.id, remote.unique_id, size/expected_size; local paths та @extra не передаються. Native minithumbnail зберігається всередині відповідного photo/video/animation/sticker object, якщо його надіслав TDLib: {"@type":"minithumbnail","width":40,"height":27,"data":"BASE64"}. Для фото читати message.content.photo.minithumbnail; data — base64 JPEG. Якщо поля немає або воно null, використовувати thumbnail/file reference через звичайний media flow. Текст та UTF-16 entities не форматуються і не обрізаються.

ПодіяЗастосування
updateNewMessageUpsert payload.message за account + message.chat_id + message.id. Подія потрібна і для закритих діалогів. Не читати старі root text/content/sender/msg_id/preview/chat_meta.
updateMessageContentЗамінити content на new_content для chat_id/message_id; native content — object з @type. Backend не викликає getMessage.
updateMessageEditedОновити edit_date/reply_markup, якщо поле присутнє. Не очищувати content, якого в цій події немає.
updateMessageEphemeralContentОновити тимчасову відповідь бота в ephemeral_content; null прибирає її. Основний content та історію повідомлення не замінювати.
updateNewWidgetQuery / updateNewInlineWidgetQuery / updateNewWidgetCopyQueryНові bot widget queries; збережено нативні поля. Відповідь через answer_widget_query; не трактувати запит як повідомлення історії.
updateMessageInteractionInfo / updateMessageReactionsЗастосувати native interaction_info/reactions. Native reactions: reactions[].type.@type, total_count, is_chosen, recent_sender_ids. Старих results/chosenOrder/reaction_senders aliases немає.
updateChatReadInbox / updateChatReadOutboxВикористовувати last_read_inbox_message_id/unread_count або last_read_outbox_message_id. Порівняння IDs через BigInt. Немає estimated read_at чи delivery_update.
updateMessageSendAcknowledged / Succeeded / FailedОбробляти native event names. Success/failure містять message і old_message_id для заміни temporary ID; failed містить native error. Повторних message_send_* events немає. Send outcome у backend ledger зберігається до live admission.
updateDeleteMessagesЗастосувати message_ids у відповідному account/chat. from_cache=true не є доказом permanent Telegram deletion.

Повідомлення, список та медіа

Native message store і parsed open_dialog DTO потребують явного frontend adapter до UI model; не змішуйте їх через object spread. Caption — content.caption.text, текст — content.text.text; messageCustomServiceAction.text є plain string. Новий native content type зберігайте з fallback renderer.

Чат-лист використовує один частковий store: доступні поля показуються відразу, невідомі — skeleton. Позиція визначає остаточний порядок і не блокує створення рядка. Склад visible/provisional rows задає windows у v3; field watermarks захищають нові значення від старих snapshots/replay.

Для видимого медіа надсилайте чинний download_file/download_files з native file id/remote.id, account, chat/message identity і чинним dialog token. Media WS прив'язаний до control WS цього пристрою. Account update сам по собі не завантажує файл, thumbnail чи emoji. Open-dialog prefetch обмежений наявним scheduler; за зайнятої черги явний download залишається доступним.

Застосовуйте native events усіх підписаних акаунтів, ізолюючи message IDs за account/chat. Об'єднуйте UI renders у короткі batches, не відкидаючи state transitions. Початкова синхронізація не повинна створювати toast для кожного історичного повідомлення; notification policy окрема від state reducer.

Rollout: frontend adapter та backend оновлюються узгоджено; reconnect усіх WS. Старих contracts/fallback немає. NATS v2 transport і JetStream archival subjects збережено. limit=50 визначає бюджет chat-list window цього пристрою; account journal і message notifications інших чатів зберігаються.

Frontend flow: поступовий chat list · tdlib_chat_list_v3

Прямий перехід на v3. Один reducer для initial entities, live та replay. Рядок не чекає position, повного вікна, avatar, sender enrichment або медіа. Protocol оголошений у connected.chat_list_protocol; v2 adapters та подвійний reducer видалити.

Підпис альбому в last_message

Якщо last_message належить до альбому та не має власного підпису, chat-list проєкція додає last_message.caption — нативний formattedText з іншого елемента того самого (userbot_id,chat_id,media_album_id). Зберігаються text та UTF-16 entities. last_message.id, sender, фото й content.caption залишаються даними останнього елемента; backend не підміняє його першим повідомленням альбому.

{"id":"155883405312","chat_id":"-1001199360700","media_album_id":"14357266778934818",
 "content":{"@type":"messagePhoto","caption":{"@type":"formattedText","text":"","entities":[]}},
 "caption":{"@type":"formattedText","text":"Підпис альбому","entities":[]}}

Frontend flow: спочатку читати власний content.caption, потім last_message.caption. Наявний frontend fallback це підтримує; нового екшену не потрібно. Для альбому без підпису annotation відсутній або null. Одиночні медіа й непорожній власний підпис зберігають попередню поведінку.

Підпис береться з обмеженого кешу нативної сесії. На холодному старті get_chats спочатку віддає доступний зріз і completion; відсутні підписи дочитуються у фоні через обмежений getChatHistory, без обходу всієї історії. Уточнення приходить звичайним revisioned chat_list_update та зберігається в snapshot/replay. Не затримувати показ списку до цього update і не запускати додаткові frontend history-запити.

Live редагування та остаточне видалення підпису змінюють annotation; null очищує його. Помилки/таймаути фонового читання не блокують список. Результати старої generation не застосовуються. Історія діалогу й нативні message updates зберігають оригінальні підписи кожного елемента.

1. Підписка і початковий зріз

Після control WS виконати open_client з повним desired account set; змінювати його лише при фактичній зміні підписок. Retained accounts не переініціалізувати. Media WS цього пристрою використовує адресу control WS. Store ізольований за account ID і generation; binding_generation — окремий transport fence.

{"action":"get_chats","userbot_id":183,"chat_list":{"@type":"chatListMain"},"limit":50}

Одна get_chats відповідь містить уже доступний узгоджений cut, включно з порожнім. loading=true означає, що owner продовжить наповнення через chat_list_update. Не повторювати get_chats лише тому, що rows менше limit. На теплому owner native load не потрібний, якщо вікно вже наповнене.

{"type":"get_chats","result":{
 "protocol":"tdlib_chat_list_v3","mode":"replace","generation":"g","revision":"100",
 "chat_list":{"@type":"chatListMain"},"after":null,"next_cursor":null,
 "chat_ids":[],"entities":{"chat":{},"user":{},"supergroup":{},"basic_group":{},"list":{},"chat_folders":{}},
 "window_limit":50,"loaded_count":0,"loading":true,"recovering":false,
 "has_more_cached":false,"list_exhausted":false,
 "windows":[{"chat_list":{"@type":"chatListMain"},"chat_ids":[],"pending_chat_ids":[],"window_limit":50,"revision":"100","refill_required":false}]}}

2. Частковий рядок і skeleton

Ключ рядка — account_id + chat_id. Entity або patch створює частковий запис; доступні поля показати відразу, невідомі залишити skeleton. Нові поля не вимагають повторного створення компонента. Відсутнє поле — не змінювати; явний null — очистити. fields є частковим набором навіть при replace=true: цей прапорець позначає передачу base, а не наказ видалити всі відсутні ключі.

Не вимагати порядку last_message → base → positions. Окремий native updateChatPosition не потрібний, якщо позиції вже є в entity. pending_order — локальний UI state.

{"type":"chat_list_update","protocol":"tdlib_chat_list_v3","generation":"g",
 "base_revision":"100","revision":"101","changes":[{
   "operation":"entity","entity":"chat","id":"42","replace":true,"generation":"g","revision":"101",
   "fields":{"id":"42","title":"Назва","positions":[]},"entities":{}}],
 "windows":[{"chat_list":{"@type":"chatListMain"},"chat_ids":[],"pending_chat_ids":["42"],"window_limit":50,"revision":"101","refill_required":false}]}

3. Membership, порядок і обмежене вікно

windows — авторитетний набір рядків, які цей WS зараз відстежує для кожного відкритого scope. chat_ids містить positioned rows у порядку (order, chat_id) descending через BigInt. pending_chat_ids — provisional rows без відомого порядку. Невідома membership показується в окремій loading-зоні; її не видавати за підтверджену Main/Archive/folder membership.

До отримання order можна показувати provisional рядок. Коли позиція приходить — перемістити той самий компонент, зберегти selection і scroll anchor. order=0 означає видалення з відповідного списку, а не повернення у pending. change.removed_positions передає явні native tombstones; fields.positions зберігає актуальні інші scopes. Рядки поза windows не рендерити, навіть якщо вони є в entity cache як dependencies.

Backend зберігає повний account journal, але передає цьому браузеру лише потрібні зміни та dependencies. Типове вікно — 50, максимум однієї сторінки — 100; сума відкритих page budgets ≤1000 на account/WS, максимум 64 scopes. Перевищення дає chat_list_invalidated з reason=chat_list_window_capacity.

Якщо рядок залишає вже наповнене вікно і наступний cached row цьому WS ще невідомий, descriptor містить refill_required=true. Виконати один get_chats для оновлення цього вікна; при чинному load спочатку дочекатися його завершення. Це реакція на зміну складу вікна, без polling/timers і без повторів лише через partial initial response. Новий baseline скидає ознаку. Native load виконується тільки за нестачі рядків у owner cache.

4. Revisions і reducer

IDs, order і revisions — decimal strings; порівнювати через BigInt. Для кожного поля entity зберігати applied revision. Snapshot entities мають watermark result.revision; change.fields та change.entities — watermark change.revision. Старе поле не перезаписує нове; старіша base може заповнити ще невідоме поле. mode=replace замінює склад вікна, не очищає весь account entity cache. Для positions watermark зберігати окремо на scope: новіший Archive snapshot не блокує старіші Main mutations, які ще не були застосовані. Відсутність чату у bounded snapshot виключає його з цього вікна на цьому cut, а не видаляє entity чи membership інших списків.

base_revision → revision підтверджує покриття цілого діапазону. changes може бути порожнім або мати пропуски номерів: непотрібні цьому вікну mutations відфільтровані. Не вимагати revision+1 для кожної change. Перевіряти суміжність діапазонів frames; дублікати застосовувати ідемпотентно. windows мають власний revision: старий descriptor не перезаписує новий, навіть якщо replay cursor ще наздоганяє snapshot.

При frame.base_revision > account cursor зберегти bounded buffer і запросити sync_chat_list. Не пересувати cursor через невідновлену прогалину. Групувати UI renders через requestAnimationFrame; прийом field mutations не повинен запускати окремий render на кожну подію.

Схема reducer (mergePositions виконує той самий per-scope watermark rule для positions і removed_positions):

function mergeFields(entity, fields, revision) {
  const r = BigInt(revision);
  for (const [key, value] of Object.entries(fields)) {
    if (key === "positions") continue;
    const previous = entity.fieldRevision.get(key);
    if (previous === undefined || r >= previous) {
      entity.fields[key] = value; // null також записується; відсутні ключі не обходяться
      entity.fieldRevision.set(key, r);
    }
  }
}

function applyBatch(account, batch) {
  requireCurrentGeneration(account, batch.generation);
  for (const change of batch.changes) {
    if (change.operation === "reset") { requestBaselineOnce(account); return; }
    const entity = account.entities.ensure(change.entity, change.id);
    mergeFields(entity, change.fields, change.revision);
    mergePositions(entity, change.fields.positions, change.removed_positions, change.revision);
    mergeDependenciesByFieldRevision(account, change.entities, change.revision);
  }
  for (const window of batch.windows) {
    const current = account.windows.get(scopeKey(window.chat_list));
    if (!current || BigInt(window.revision) >= BigInt(current.revision)) {
      account.windows.set(scopeKey(window.chat_list), window);
    }
  }
  recordCoveredRange(account, batch.base_revision, batch.revision);
  advanceContiguousCursor(account); // пропуск frames викликає один sync, cursor через gap не перескакує
  scheduleOneAnimationFrame();
}

5. Завершення, помилки та pagination

Після наповнення сторінки owner надсилає адресний chat_list_load_complete з command_id та result: protocol, generation, revision, chat_list, window_limit, loaded_count, next_cursor, list_exhausted, loading і recovering. Повторного повного snapshot немає. Completion може випередити queued live suffix: закінчити loading UI після покриття його revision, за необхідності через replay.

get_chats_error/load_chats_error — terminal command outcomes. Entity list додатково містить loading/exhausted/error/error_code/retryable. Native 404 встановлює exhaustion; порожня порція сама цього не доводить. Cancellation не встановлює exhausted=true.

{"action":"load_chats","userbot_id":183,"chat_list":{"@type":"chatListMain"},"limit":50,
 "after":{"order":"7697569550442830318","chat_id":"42"}}

load_chats використовує той самий handler: initial mode=append з after, incremental updates, потім короткий completion. Наступний cursor брати з completion. Повтор тієї самої сторінки не розширює budget. Scope з власним replace baseline не повинен пересувати account cursor через updates інших відкритих scopes.

6. Replay, reconnect і зміна generation

{"action":"sync_chat_list","userbot_id":183,"generation":"g","since_revision":"101","change_limit":500}

На поточному WS sync продовжує вже створені windows і проходить той самий reducer. При has_more продовжувати з result.revision, не target_revision. Generation mismatch, trimmed journal або chat_list_invalidated вимагають одного get_chats для потрібних scopes; зберігати старі рядки як stale до нового baseline.

Новий WS створює власні bounded windows через get_chats для потрібних scopes. Старий store можна показувати як stale, але самого persisted cursor недостатньо для відновлення server-side window. Sync без baseline дає chat_list_invalidated(reason=chat_list_baseline_required). Не запускати retry polling. При відписці скасувати pending scope requests, timers та buffers; стару binding/generation відкидати.

7. Приймання й видалення старого flow

Видалити очікування 50 rows, окремої position, get_chats_end/chunks, JSON Patch і паралельний reducer raw native updates для chat list. Notification/message events інших діалогів зберігають свій контракт; не відкидати їх через chat-list window. Open dialog та media не змінені цією міграцією.

Перевірити cold/warm owner, новий пристрій, 10 підключень, partial-before-base, null/absent, positions у last-message update, order=0, scroll, delayed snapshots, duplicates/gaps, replay, reconnect і cancellation. Виміряти першу entity, перший skeleton/visible row, перший positioned row, готовність сторінки, delivery queue wait, кількість frames/bytes і browser long tasks. Backend не вимірює browser render.

Повторне читання історії та recovery

Кожен новий open_dialog або sync_history, включно з повторним читанням того самого cursor, отримує окремий command ID. Якщо frontend передає власний client_request_id, використовуйте нове значення для кожного логічного читання. Backend зберігає command ID при транспортній повторній доставці. Змінювати cursor лише заради обходу dedupe не потрібно.

Подія telegram_update_gap з result.recovered:true підтверджує відновлення account state. За reset_required:true виконайте вказані reset_actions для чинних підписок і відкритого діалогу.

Додатковий масив result.history_windows_reset містить діалоги, історію яких не вдалося відновити: chat_id, method, error_code, error, retryable. Їхній кеш інвалідовано; збережені повідомлення не можна вважати актуальною відновленою історією. Це не означає видалення повідомлень у Telegram. Помилка одного history window не перезапускає chat-list generation усього акаунта.

Адресна доставка на пристрій

Telegram-акаунт має один owner і одну TDLib-сесію. Кожен пристрій має власний control WS ID з події connected, активний діалог і dialog token. Відповіді на команди та історія доставляються запитувачу; спільні зміни списку чатів і стану акаунта — його підписникам.

Media WS прив’язуйте через control_ws_connection_id до control WS цього пристрою. Перепідключення лише media WS зберігає цю адресу; після перепідключення control WS використовуйте новий ID. Запити різних пристроїв на один файл ділять завантаження, але кожен отримує власний результат. Відключення одного запитувача не скасовує завантаження для інших.

Формат WS payload не змінився. _meta.live_subject — діагностичне поле внутрішньої маршрутизації NATS; frontend не повинен його парсити. Продовжуйте перевіряти account, dialog token і binding generation.