tg_client WebSocket Docs: Domain Core Reference
← Назад до розділів | Оновлення
Знайдено секцій: 0
Workflow (загальний)
- Frontend підключає control socket до
/ws/chats/і отримуєconnected.ws_connection_id. - Frontend надсилає
{"action":"open_client","userbot_ids":[...],"client_request_id":"unique-id"}у control socket і чекає відповіднийopen_client_ready. - Bootstrap/sync списку можна запитувати відразу після ack. Паралельно frontend підключає media socket до
/ws/chats/media/і прив'язує черезopen_media_stream; media-команди починає післяmedia_stream_ready. - Надсилає команди (
open_dialog,send_message, ...). - Consumer публікує owner command у NATS JetStream subject відповідного shard.
- Shard owner отримує команду, виконує TDLib методи і публікує відповіді в NATS live subject акаунта.
- Live updates, command responses і media events публікуються в
TG_EVTта transient Core NATS subjectsrt.*.tg.evt.acc.{userbot_id}.>. - 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_message | chat_id, message_id | getFullRichMessage → richMessage; викликати на вимогу, якщо is_full=false. Не завантажувати окремо для кожного повідомлення історії. |
| get_message_properties | chat_id, message_id | getMessageProperties → messageProperties. Перевірка can_add_tasks, can_mark_tasks_as_done, can_be_edited та інших прав. |
| parse_text_entities | text, parse_mode | parseTextEntities → formattedText. parse_mode: HTML, MarkdownV2 або нативний textParseModeHTML/textParseModeMarkdown. |
| get_text_entities | text | getTextEntities → textEntities; URL, згадки, хештеги та інші автоматичні entities. |
| edit_message_checklist | chat_id, message_id, checklist, опц. reply_markup | editMessageChecklist → message. |
| add_checklist_tasks | chat_id, message_id, tasks[] | addChecklistTasks → ok. Елементи: inputChecklistTask з унікальними позитивними int32 id та formattedText text. |
| mark_checklist_tasks_as_done | chat_id, message_id, marked_as_done_task_ids[], marked_as_not_done_task_ids[] | markChecklistTasksAsDone → ok; один id не може бути в обох масивах. Підсумковий стан приходить через updateMessageContent. |
| get_widget_public_data | chat_id, message_id | getWidgetPublicData → widgetPublicData (data, poll_period). Лише для видимих віджетів, які попросили watchPublicData; об'єднувати polling за widget_id та дотримуватися poll_period. |
| get_widget_query_answer | chat_id, message_id, query_type, data | getWidgetQueryAnswer → widgetQueryAnswer. data — base64 від 1–64 UTF-8 байтів. Підтримано widgetQueryTypeData без wallet. Це взаємодія з ботом, тому команда не класифікується як read-only. |
| edit_message_widget_data | chat_id, message_id, edit_public_data, public_data, edit_chat_data, chat_data | editMessageWidgetData → ok; для ботів. Окремі edit_* прапорці відрізняють незмінене поле від очищення порожнім рядком. |
| edit_inline_message_widget_data | inline_message_id, edit_public_data, public_data, edit_chat_data, chat_data | editInlineMessageWidgetData → ok; для ботів. |
| edit_widget_data | widget_id, public_data, cache_time | editWidgetData → ok; для ботів, спільний стан shared widget. |
| answer_widget_query | widget_query_id, data | answerWidgetQuery → ok; для ботів. data — UTF-8 рядок до 1024 байтів. |
| delete_message_ephemeral_content | chat_id, message_id | deleteMessageEphemeralContent → 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 | — | Запис відео. |
| chatActionUploadingVideo | progress: int32, 0–100 | Надсилання відео. |
| chatActionRecordingVoiceNote | — | Запис голосового повідомлення. |
| chatActionUploadingVoiceNote | progress: int32, 0–100 | Надсилання голосового повідомлення. |
| chatActionUploadingPhoto | progress: int32, 0–100 | Надсилання фото. |
| chatActionUploadingDocument | progress: int32, 0–100 | Надсилання документа. |
| chatActionChoosingSticker | — | Вибір стікера. |
| chatActionChoosingLocation | — | Вибір геолокації або закладу. |
| chatActionChoosingContact | — | Вибір контакту. |
| chatActionStartPlayingGame | — | Початок гри. |
| chatActionRecordingVideoNote | — | Запис відеоповідомлення. |
| chatActionUploadingVideoNote | progress: int32, 0–100 | Надсилання відеоповідомлення. |
| chatActionWatchingAnimations | emoji: string | Натискання анімованого emoji співрозмовника. |
| chatActionCancel | — | Скасування попередньої активності; також можна передати chat_action:null. |
Типи без додаткових полів можна передавати рядком, наприклад "chat_action":"chatActionTyping".
Для upload прогрес має тип integer; якщо відсутній, передається 0. Це повідомлення про активність:
воно не завантажує файл і не починає запис мікрофона чи камери.
Усі типи MessageTopic
| topic_id.@type | Ідентифікатор |
|---|---|
| messageTopicThread | message_thread_id: int53 |
| messageTopicForum | forum_topic_id: int32 |
| messageTopicDirectMessages | direct_messages_chat_topic_id: int53 |
| messageTopicSavedMessages | saved_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 і відображається як раніше.
Link preview: редактор, історія та фото
Після open_client_ready запитувати прев’ю через control WS.
text — formattedText або рядок; link_preview_options необов’язкове.
Немає прев’ю (у тому числі TDLib 404) — успішний result:null;
інші помилки повертаються як get_link_preview_error зі звичною кореляцією.
{"action":"get_link_preview","userbot_id":211,"client_request_id":"draft-preview-1",
"text":{"@type":"formattedText","text":"https://github.com/microsoft/vscode","entities":[]}}
{"type":"get_link_preview","userbot_id":211,"client_request_id":"draft-preview-1",
"result":{"@type":"linkPreview","url":"https://github.com/microsoft/vscode","site_name":"GitHub",
"title":"Visual Studio Code","description":{"@type":"formattedText","text":"…","entities":[]}}}
При зміні URL робити debounce, присвоювати новий request ID та ігнорувати відповідь від попередньої версії чернетки/акаунта. Закриття картки зберігає посилання в тексті та вимикає прев’ю для відправлення; нова чернетка або новий URL потребують окремого стану dismissal.
{"action":"send_message","userbot_id":211,"chat_id":"123","client_request_id":"send-text-1",
"text":{"@type":"formattedText","text":"https://github.com/microsoft/vscode","entities":[]},
"link_preview_options":{"@type":"linkPreviewOptions","is_disabled":true}}
send_comment приймає те саме поле разом зі своїми параметрами коментаря.
У open_dialog, history, search_messages_in_chat,
search_messages_global текстове повідомлення містить верхній
link_preview: linkPreview | null. Поле content:[] збережене.
{"msg_id":"8032092160","type_msg":"messageText","content":[],
"link_preview":{"@type":"linkPreview","url":"https://example.com","site_name":"Example",
"title":"Заголовок","description":{"@type":"formattedText","text":"Опис","entities":[]},
"type":{"@type":"linkPreviewTypePhoto","photo":{"sizes":[{"type":"x","width":800,"height":502,
"photo":{"id":"4849","remote":{"id":"REMOTE_ID","unique_id":"UNIQUE_ID"}}}]}}}}
Live TDLib-події зберігають прев’ю в message.content.link_preview або
new_content.link_preview. Адаптер має об’єднати ці джерела з плоским history DTO.
Фото надісланого повідомлення завантажується звичайним запитом нижче; backend шукає файл також
у вкладеному preview, а результат надходить як media_ready. Додати чинний dialog token,
якщо його вимагає поточний media scope.
{"action":"download_file","userbot_id":211,"chat_id":"-1002672487135",
"msg_id":"8032092160","remote_id":"REMOTE_ID"}
Для чернетки ще немає message ID: не підставляти ID стороннього повідомлення. Передати нативний
file reference з відповіді get_link_preview, використовуючи source:"remote" без chat/msg ID.
Після media_ready звірити remote ID та актуальність чернетки; метадані картки можна показати відразу.
{"action":"download_file","userbot_id":211,"source":"remote",
"file_id":"4849","remote_id":"REMOTE_ID"}
Стан діалогу: 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
}
}
| Поле | Контракт і використання |
|---|---|
| profilePhotoUrl | Nullable URL збереженого фото. Storage key зберігається в backend; URL може перевидаватися. Null можливий без фото або до завершення фонового завантаження. |
| profilePhotoRemoteId / profilePhotoUniqueId | Nullable рядки ідентичності фото; зміна інвалідовує frontend avatar cache. Не використовувати URL як єдину ідентичність фото. |
| profilePhotoMinithumbnail | Nullable 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 — у довіднику авторизації.
Два 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 | Відео. | Медіа |
searchMessagesFilterVoiceNote | Voice. | Голосові |
searchMessagesFilterPhotoAndVideo | Фото + відео. | Медіа |
searchMessagesFilterUrl | Повідомлення з URL. | Посилання |
searchMessagesFilterChatPhoto | Оновлення фото чату. | Системні |
searchMessagesFilterVideoNote | Video note. | Голосові |
searchMessagesFilterVoiceAndVideoNote | Voice + 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_settings | userbot_id, chat_id | Поточні налаштування чату разом із is_muted, mute_until, is_muted_forever. |
set_chat_notification_settings | chat_id, notification_settings або окремі поля | Частково змінює message/story preview, sounds, mute, mention та pinned-message notifications. |
mute_chat / unmute_chat | chat_id; для mute — mute_for/duration | Швидкий mute на секунди, 1h, 8h, 3d, forever, або unmute. |
reset_chat_notification_settings | chat_id | Повертає всі chat overrides до відповідного глобального scope. |
get_scope_notification_settings / set_scope_notification_settings | scope: private, group, channel | Глобальні налаштування типу чатів. |
get_chat_notification_settings_exceptions | опц. scope, compare_sound | Чати з settings, що відрізняються від scope defaults. |
get_forum_topic_notification_settings / set_forum_topic_notification_settings | chat_id, message_thread_id, для set — settings | Читає або частково змінює окремі налаштування forum topic. Кожен item у get_forum_topics також містить актуальний об’єкт notification_settings. |
mute_forum_topic / unmute_forum_topic | chat_id, message_thread_id; для mute опц. mute_for/duration або mute_until | Мутить лише вибраний topic, не весь чат. Без тривалості mute_forum_topic використовує forever; unmute встановлює mute_for=0. |
set_reaction_notification_settings | message_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_sound | file_id/remote_id; для remove — notification_sound_id | Додає або видаляє custom sound. |
reset_all_notification_settings | userbot_id | Скидає всі chat і scope settings до Telegram defaults. |
configure_notification_api | notification_group_count_max (0–25), notification_group_size_max (1–25) | Opt-in в active Notification API; count=0 вимикає її. |
remove_notification | notification_group_id, notification_id | Підтверджує TDLib, що користувач прибрав одне активне сповіщення. |
remove_notification_group | notification_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-поля й невідомі параметри не приймаються.
| Action | Native-параметри крім userbot_id | Результат TDLib | Метод | Мутація |
|---|---|---|---|---|
get_sticker_set | set_id: int64 | StickerSet | getStickerSet | Ні |
search_sticker_set | name: string, ignore_cache: Bool (типово false) | StickerSet | searchStickerSet | Ні |
get_archived_sticker_sets | sticker_type: StickerType, offset_sticker_set_id: int64, limit: int32 | StickerSets | getArchivedStickerSets | Ні |
get_trending_sticker_sets | sticker_type: StickerType, offset: int32, limit: int32 | TrendingStickerSets | getTrendingStickerSets | Ні |
search_sticker_sets | sticker_type: StickerType, query: string | StickerSets | searchStickerSets | Ні |
change_sticker_set | set_id: int64, is_installed: Bool, is_archived: Bool | Ok | changeStickerSet | Так |
reorder_installed_sticker_sets | sticker_type: StickerType, sticker_set_ids: vector<int64> | Ok | reorderInstalledStickerSets | Так |
get_favorite_stickers | Немає | Stickers | getFavoriteStickers | Ні |
add_favorite_sticker | sticker: InputFile | Ok | addFavoriteSticker | Так |
remove_favorite_sticker | sticker: InputFile | Ok | removeFavoriteSticker | Так |
remove_recent_sticker | is_attached: Bool, sticker: InputFile | Ok | removeRecentSticker | Так |
clear_recent_stickers | is_attached: Bool | Ok | clearRecentStickers | Так |
get_stickers | sticker_type: StickerType, query: string, chat_id: int53, limit: int32 | Stickers | getStickers | Ні |
search_stickers | sticker_type: StickerType, emojis: string, query: string, input_language_codes: vector<string>, offset: int32, limit: int32 | Stickers | searchStickers | Ні |
get_emoji_categories | type: EmojiCategoryType | EmojiCategories | getEmojiCategories | Ні |
search_emojis | text: string, input_language_codes: vector<string> | EmojiKeywords | searchEmojis | Ні |
get_installed_sticker_sets | sticker_type: StickerType | StickerSets | getInstalledStickerSets | Ні |
get_recent_stickers | is_attached: Bool | Stickers | getRecentStickers | Ні |
get_saved_animations | Немає | Animations | getSavedAnimations | Ні |
add_saved_animation | animation: InputFile | Ok | addSavedAnimation | Так |
remove_saved_animation | animation: InputFile | Ok | removeSavedAnimation | Так |
search_gifs | query: string, offset: string | InlineQueryResults | getInlineQueryResults | Ні |
Native-пагінація та результати
get_installed_sticker_sets→stickerSets{total_count,sets}: весь native-список metadata наборів; штучних limit/offset немає. Вміст окремого набору —get_sticker_set(set_id).get_archived_sticker_sets: cursoroffset_sticker_set_id("0" для початку), limit до 100. Наступний cursor —sets[-1].id; порожня сторінка завершує список.get_trending_sticker_sets: offset/limit;trendingStickerSets{total_count,sets,is_premium}. total_count приблизний, як у TDLib.search_sticker_sets: лише sticker_type/query. TDLib не має offset/limit для цього методу.get_saved_animations→animations{animations}. Списки стікерів →stickers{stickers}; пошук звичайних емодзі →emojiKeywords{emoji_keywords}.- Backend зберігає native-поля
id,set_id,full_type,sticker/animation,remote. Немає додаткових items/count/pagination/download DTO. Локальні файлові шляхи видаляються, ID безпечно серіалізуються рядками.
Приклади
{"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.
Коли приходить:
download_file— після ручного завантаження файлу;get_chatsіget_recently_opened_chats— тільки для аватарок і preview;search_messages_in_chatіsearch_messages_global— тільки для аватарок і preview;open_dialog— для повного медіа та custom emoji;get_custom_emoji_media— для пакетного завантаження custom emoji по масиву id, зокрема для видимих елементів зі sticker pack;
User / Chat Profiles / Contacts
| Action | Що приймає | Що повертає | Що робить |
|---|---|---|---|
search_user |
userbot_id, 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. |
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_id | Telegram accent color для чату. | Опціонально стилізувати avatar ring/title badge. |
background_custom_emoji_id | ID custom emoji для background чату, "0" якщо відсутній. | Якщо не "0" - завантажувати відповідний decoration. |
profile_accent_color_id | Accent color профілю чату, -1 якщо дефолт. | Використовувати fallback, якщо значення -1. |
profile_background_custom_emoji_id | Custom 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_topics | UI режим показу як список тем. | Відкривати чат у режимі 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_time | TTL автознищення повідомлень у секундах, 0 = вимкнено. | Показувати current auto-delete value. |
theme_name | Тема чату (якщо застосовується). | Опційно стилізувати чат або ігнорувати пусте значення. |
reply_markup_message_id | ID повідомлення з активним 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 | Дозвіл надсилати текстові повідомлення. | true | Composer активний. |
can_send_audios | Дозвіл надсилати аудіофайли. | true | Audio upload доступний. |
can_send_documents | Дозвіл надсилати документи/файли. | true | File picker доступний. |
can_send_photos | Дозвіл надсилати фото. | true | Photo upload доступний. |
can_send_videos | Дозвіл надсилати відео. | true | Video upload доступний. |
can_send_video_notes | Дозвіл надсилати video notes. | true | Video note action доступний. |
can_send_voice_notes | Дозвіл надсилати voice notes. | true | Мікрофон доступний. |
can_send_polls | Дозвіл створювати опитування. | true | Poll action доступний. |
can_send_other_messages | Дозвіл надсилати sticker/GIF/інші типи. | true | Sticker/GIF picker доступний. |
can_add_link_previews | Дозвіл додавати preview до URL. | true | Toggle preview доступний. |
can_change_info | Дозвіл редагувати назву/опис/аватар. | false | Edit chat profile прихований. |
can_invite_users | Дозвіл запрошувати нових учасників. | true | Invite member доступний. |
can_pin_messages | Дозвіл закріплювати повідомлення. | false | Pin message action заблокований. |
can_create_topics | Дозвіл створювати нові теми. | false | Create 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_for | Mute duration в секундах. | 376070182 | Показувати чат як muted. |
use_default_sound | Використовувати глобальний звук. | true | Local sound picker можна ховати/дизейблити. |
sound_id | ID локального sound. | "-1" | Зазвичай дефолтний звук. |
use_default_show_preview | Використовувати глобальний show preview. | true | Preview toggle наслідує global state. |
show_preview | Локальний прапорець preview. | false | Працює лише якщо use_default_show_preview=false. |
use_default_mute_stories | Використовувати глобальний mute stories. | true | Stories mute контролюється глобальним налаштуванням. |
mute_stories | Локальний mute для stories. | false | Працює лише при use_default_mute_stories=false. |
use_default_story_sound | Використовувати глобальний звук stories. | true | Story sound picker наслідує глобальний. |
story_sound_id | ID звуку stories. | "-1" | Дефолтний story sound. |
use_default_show_story_sender | Використовувати глобальне відображення автора story. | true | Story 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. | true | Mention 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 | Тип обʼєкта супергрупи. | supergroup | Type guard. |
id | ID супергрупи. | 1987658875 | Використовувати у TDLib методах супергрупи. |
usernames.@type | Тип обʼєкта usernames. | usernames | Type guard. |
usernames.active_usernames | Активні username. | ["romaniaitcommunity"] | Показати public links. |
usernames.disabled_usernames | Вимкнені username. | [] | Зазвичай не показувати в публічному UI. |
usernames.editable_username | Username, який можна редагувати власнику/адміну. | "romaniaitcommunity" | В admin UI ставити в поле editable username. |
date | Unix 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 | Чи має повʼязаний чат. | false | Linked chat section приховати. |
has_location | Чи має група геолокацію. | false | Location 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. | false | Slow 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. | false | Stories ring не показувати. |
has_unread_active_stories | Є непрочитані stories. | false | Stories unread badge не показувати. |
Розшифровка supergroup_full_info (повністю)
| Поле | Опис | Поточне значення | Вплив на UI |
|---|---|---|---|
@type | Тип обʼєкта. | supergroupFullInfo | Type guard. |
description | Опис чату. | "" | About-блок порожній. |
member_count | Кількість учасників. | 2048 | Показати в header/about. |
administrator_count | Кількість адміністраторів. | 0 | Admin count = 0 або приховати. |
restricted_count | Кількість restricted users. | 0 | Moderation counters. |
banned_count | Кількість забанених. | 0 | Moderation counters. |
linked_chat_id | ID повʼязаного чату. | 0 | Linked chat section приховати. |
slow_mode_delay | Інтервал slow mode (сек). | 0 | Slow mode неактивний. |
slow_mode_delay_expires_in | Залишок таймера slow mode. | 0.0 | Timer не показувати. |
can_enable_paid_reaction | Чи можна увімкнути paid reactions. | false | Paid reactions toggle заблокований. |
can_get_members | Чи можна отримати список учасників. | true | Members tab доступний. |
has_hidden_members | Чи прихований список учасників. | true | Показати обмеження видимості member list. |
can_hide_members | Чи можна керувати приховуванням members. | false | Admin control hide members недоступний. |
can_set_sticker_set | Чи можна встановити sticker set. | false | Sticker set editor недоступний. |
can_set_location | Чи можна встановити geolocation. | false | Location editor недоступний. |
can_get_statistics | Чи доступна статистика чату. | false | Statistics screen приховати. |
can_get_revenue_statistics | Чи доступна revenue статистика. | false | Revenue section приховати. |
can_get_star_revenue_statistics | Чи доступна Star revenue статистика. | false | Star revenue section приховати. |
can_toggle_aggressive_anti_spam | Чи можна керувати aggressive anti-spam. | false | Anti-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. | false | Anti-spam status = off. |
has_paid_media_allowed | Чи дозволений paid media. | false | Paid media composer actions вимкнені. |
has_pinned_stories | Чи є pinned stories. | false | Pinned stories block приховати. |
my_boost_count | Скільки бустів користувач дав чату. | 0 | Boost contribution badge = 0. |
unrestrict_boost_count | Скільки бустів треба для зняття обмежень. | 0 | Restriction boost hint не потрібен. |
sticker_set_id | ID sticker set чату. | "0" | Sticker set не заданий. |
custom_emoji_sticker_set_id | ID 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_id | ID basic group, з якої мігрували. | 0 | Міграції не було. |
upgraded_from_max_message_id | Максимальний msg id на момент міграції. | 0 | Міграції не було. |
Розшифровка bot_commands
| Поле | Опис | Поточне значення |
|---|---|---|
bot_commands[0].@type | Тип контейнера команд бота. | botCommands |
bot_commands[0].bot_user_id | User ID бота, якому належать команди. | 313092884 |
bot_commands[0].commands[0].@type | Тип обʼєкта команди. | botCommand |
bot_commands[0].commands[0].command | Slash-команда. | "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 | Непрочитані повідомлення. | 45 | Badge unread. |
unread_mention_count | Непрочитані згадки. | 0 | Mention badge відсутній. |
unread_reaction_count | Непрочитані реакції. | 0 | Reaction 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. | false | Forward/save не блокувати цим прапорцем. |
profile_photo | Фото каналу. | file_id 4158 + sizes | Вибирати size за DPI/контейнером. |
chat_full_info | Детальний обʼєкт chat. | {} | Перевіряти на порожній обʼєкт перед рендером. |
permissions для channel (повністю)
| Поле | Поточне значення | Що це означає у UI |
|---|---|---|
can_send_basic_messages | false | Text composer вимкнений. |
can_send_audios | false | Audio upload вимкнений. |
can_send_documents | false | File upload вимкнений. |
can_send_photos | false | Photo upload вимкнений. |
can_send_videos | false | Video upload вимкнений. |
can_send_video_notes | false | Video notes вимкнені. |
can_send_voice_notes | false | Mic/voice вимкнений. |
can_send_polls | false | Create poll вимкнений. |
can_send_other_messages | false | GIF/sticker/emoji media вимкнені. |
can_add_link_previews | false | Link preview toggle вимкнений. |
can_change_info | false | Edit profile channel hidden/disabled. |
can_invite_users | false | Invite UI hidden/disabled. |
can_pin_messages | false | Pin action hidden/disabled. |
can_create_topics | false | Create topic hidden/disabled (канал без тем). |
supergroup для channel (повністю)
| Поле | Поточне значення | Вплив на фронт |
|---|---|---|
is_channel | true | Канал, не група. |
is_forum | false | Режим тем не використовувати. |
member_count | 11696 | Показувати subscriber count. |
boost_level | 2 | Показувати boost badge. |
has_linked_chat | true | Показувати блок linked chat. |
sign_messages | false | Автор постів як підпис не показується. |
show_message_sender | false | Sender line у пості не показувати. |
join_to_send_messages | true | Для non-member показати CTA Join. |
join_by_request | false | Join без заявки. |
is_slow_mode_enabled | false | Slow mode індикатор не показувати. |
has_sensitive_content | false | Без sensitive warning. |
restriction_reason | "" | Restriction banner не показувати. |
has_active_stories | false | Stories ring не показувати. |
has_unread_active_stories | false | Stories unread badge не показувати. |
supergroup_full_info для channel (повністю)
| Поле | Поточне значення | Вплив на фронт |
|---|---|---|
description | непорожній текст + посилання | Рендерити multi-line about з активними URL. |
linked_chat_id | -1002435456208 | Кнопка "Discuss" / перехід у linked chat. |
can_get_members | false | Members list/tab недоступний. |
has_hidden_members | true | Показати, що список підписників приховано. |
can_enable_paid_reaction | true | Admin toggle paid reactions може бути доступний. |
has_paid_media_allowed | true | Paid media можливий у цьому каналі. |
has_pinned_stories | true | Показувати блок pinned stories. |
is_all_history_available | true | Вся історія доступна. |
can_have_sponsored_messages | true | Підтримувати маркер sponsored posts. |
bot_commands | [] | Slash-command hints не показувати. |
can_get_statistics | false | Statistics розділ приховати. |
can_get_revenue_statistics | false | Revenue statistics приховати. |
can_get_star_revenue_statistics | false | Star revenue statistics приховати. |
can_toggle_aggressive_anti_spam | false | Anti-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.@type | chatTypeBasicGroup | Рендерити group UI, не channel і не forum. |
type.basic_group_id | 232048874 | Використовувати для базових group-операцій. |
positions | [] | Позиція може братися з chat_lists/локального сортування. |
chat_lists | folder 22 + main | Показувати належність до папки і main list. |
profile_photo | null | Показувати fallback avatar з ініціалами. |
supergroup | null | Supergroup-поля не використовувати. |
basic_group | object | Основне джерело статусу/типу участі в basic group. |
basic_group_full_info | object | Джерело members/invite link/creator info. |
can_be_deleted_only_for_self | true | У delete-dialog показати локальне видалення як доступне. |
can_be_deleted_for_all_users | true | Показати "delete for all users" як доступну дію (якщо UX це підтримує). |
can_be_reported | false | Action report приховати. |
permissions для basic group (повністю)
| Поле | Поточне значення | Вплив на UI |
|---|---|---|
can_send_basic_messages | true | Text composer активний. |
can_send_audios | true | Audio upload активний. |
can_send_documents | true | File upload активний. |
can_send_photos | true | Photo upload активний. |
can_send_videos | true | Video upload активний. |
can_send_video_notes | true | Video notes активні. |
can_send_voice_notes | true | Mic/voice активний. |
can_send_polls | true | Create poll активний. |
can_send_other_messages | true | GIF/sticker/emoji media активні. |
can_add_link_previews | true | Link preview toggle активний. |
can_change_info | true | Edit group info доступний. |
can_invite_users | true | Invite users доступний. |
can_pin_messages | true | Pin message доступний. |
can_create_topics | true | Create topic UI можна показувати, якщо функція підтримується в поточній версії. |
basic_group і basic_group_full_info (повністю)
| Поле | Поточне значення | Вплив на фронт |
|---|---|---|
basic_group.id | 232048874 | Груповий ID для карток/кешу. |
basic_group.member_count | 2 | Показувати member count. |
basic_group.status.@type | chatMemberStatusCreator | Поточний користувач є creator (адмін максимум). |
basic_group.status.custom_title | "" | Кастомний admin title відсутній. |
basic_group.status.is_anonymous | false | Анонімний режим адміна вимкнений. |
basic_group.status.is_member | true | Користувач є учасником групи. |
basic_group.is_active | true | Група активна. |
basic_group.upgraded_to_supergroup_id | 0 | Не мігровано в supergroup. |
basic_group_full_info.description | "" | About секція порожня. |
basic_group_full_info.creator_user_id | 410102970 | Позначити creator у member list. |
basic_group_full_info.members | 2 members | Рендер списку учасників з ролями і датами join. |
basic_group_full_info.can_hide_members | false | Hide members control недоступний. |
basic_group_full_info.can_toggle_aggressive_anti_spam | false | Aggressive anti-spam toggle недоступний. |
basic_group_full_info.invite_link.invite_link | https://t.me/+vCoG9XuaHRs3YTAy | Показати/скопіювати primary invite link. |
basic_group_full_info.invite_link.creates_join_request | false | Join by direct invite, без заявки. |
basic_group_full_info.invite_link.is_primary | true | Це primary invite link. |
basic_group_full_info.invite_link.is_revoked | false | Посилання активне. |
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_story | story_poster_chat_id, story_id, опц. only_local | Отримати конкретну доступну story. |
download_story | story_poster_chat_id, story_id | Отримати story разом із media_files[]. Для фактичного CDN-завантаження передайте ці файли в існуючий download_files. |
get_chat_active_stories | chat_id | Активні stories чату, які поточний акаунт може переглянути. |
get_chat_archived_stories | chat_id, опц. from_story_id, limit | Архів власних/керованих stories; потрібне право edit stories. |
get_chat_posted_stories | chat_id, опц. from_story_id, limit | Stories, збережені на сторінці профілю чату. |
get_chats_to_post_stories | userbot_id | Чати, від імені яких акаунт може публікувати stories. |
can_post_story | chat_id | Перевірити право і поточні обмеження публікації. |
post_story | chat_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_story | story_poster_chat_id, story_id, опц. content, areas, caption | Редагування доступної story. |
delete_story | story_poster_chat_id, story_id | Видалення story. |
open_story / close_story | story_poster_chat_id, story_id | Позначити story відкритою/закритою; open_story реєструє перегляд у Telegram. |
get_story_interactions | story_id, опц. story_poster_chat_id, offset, limit, filters | Перегляди, реакції, forwards/reposts. Для story каналу передайте story_poster_chat_id. |
set_story_privacy_settings | story_id, privacy_settings | Зміна аудиторії власної story. |
set_story_reaction | story_poster_chat_id, story_id, reaction_type | Поставити або прибрати реакцію (null). |
reply_to_story | story_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_page | story_poster_chat_id, story_id, is_posted_to_chat_page | Залишити/прибрати story зі сторінки профілю після завершення. |
set_chat_pinned_stories | chat_id, story_ids[] | Атомарно замінює повний список прикріплених stories через TDLib setChatPinnedStories. Усі stories спочатку мають бути опубліковані на сторінці чату. |
pin_story / unpin_story | chat_id, story_id | Зручний CRUD одного pin: backend читає поточні pinned_story_ids, змінює потрібний ID і записує повний список. |
set_chat_active_stories_list | chat_id, story_list: main/archive або TDLib object | Переміщує активний story-feed чату між основним списком та архівом через setChatActiveStoriesList. |
archive_chat_stories / unarchive_chat_stories | chat_id | Alias-и для storyListArchive та storyListMain. Це архівування feed конкретного чату, а не примусове завершення власної story. |
get_chat_story_albums | chat_id | Повертає всі story albums чату. Потребує TDLib schema з getChatStoryAlbums; на старій бібліотеці повертає нормалізовану non-retryable capability error. |
get_story_album_stories | chat_id, story_album_id, опц. offset, limit | Повертає stories конкретного альбому з offset-пагінацією. |
create_story_album | chat_id, name (1–12 символів), опц. story_ids[] | Створює story album і за потреби одразу додає stories. |
edit_story_album | chat_id, story_album_id, name | Перейменовує story album через setStoryAlbumName. |
delete_story_album | chat_id, story_album_id | Видаляє story album. |
add_stories_to_story_album / remove_stories_from_story_album | chat_id, story_album_id, story_ids[] | Додає stories на початок альбому або видаляє їх з альбому. |
reorder_story_album_stories | chat_id, story_album_id, story_ids[] | Переміщує вказані stories на початок альбому в заданому порядку; решта зберігає поточний порядок. |
reorder_story_albums | chat_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 | Значення |
|---|---|
inputStoryContentPhoto | photo як inputFileId/inputFileRemote, опц. added_sticker_file_ids[]. |
inputStoryContentVideo | video, 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 не форматуються і не обрізаються.
| Подія | Застосування |
|---|---|
| updateNewMessage | Upsert 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.