Оновлення для фронтенду

· WS та GraphQL · лише зміни бекенду

Короткий перелік змін для інтеграції. Приклади запитів, поля та помилки — за посиланнями в кожному пункті. Це контракт змін у коді; доступність на стенді перевіряйте після його оновлення.

1. Початок інтеграції та сумісність

Флоу: control WS → open_client → open_client_ready → get_messenger_capabilities. Вмикати можливості за прапорцями; Widget API потребує TDLib 1.8.70+. На старій бібліотеці можливий result.code: TDLIB_UPGRADE_REQUIRED.

Кожному новому логічному запиту — новий client_request_id; відповіді звіряти з акаунтом і діалогом. Нові команди повертають <action> / <action>_error. Capabilities не замінюють права користувача, Premium та bot-only обмеження.

Повний контракт екшенів і capabilities

3. Форматування, альбоми та каруселі

Екшени: parse_text_entities, get_text_entities, send_message, send_comment, edit_message.

Флоу: HTML/MarkdownV2 → parse_text_entities → formattedText. Зберігати UTF-16 offsets і параметри entities: код, цитати, дати, timestamps, custom emoji.

Альбом — media_items (2–10), групування за media_album_id. Фото/відео можна змішувати; документи й аудіо — лише однорідні групи. Підтримані caption/entities та show_caption_above_media. Rich-каруселі — pageBlockSlideshow.

Повний upload/send flow альбомів · Форматування і rich blocks

4. Нові картки, кнопки та повний контент

Історія додає native_content для rich messages, чеклістів, віджетів, подарунків, giveaway, paid media та невідомих типів. Звести його й live TDLib-контент до однієї UI-моделі; невідомому типу залишити fallback. Зберігати стилі кнопок та icon_custom_emoji_id.

Флоу: доступні blocks → лише при is_full:false і потребі викликати get_full_rich_message. Відправляти через input_message_content; вкладені файли — через звичайний local-upload:.

Повний контракт карток і відправлення

5. Чеклісти

Екшени: get_message_properties, edit_message_checklist, add_checklist_tasks, mark_checklist_tasks_as_done.

Флоу: перевірити права → передати task IDs → остаточний стан з updateMessageContent. Читати list.tasks, completed_by, completion_date; done/undone масиви не можуть містити однаковий ID.

Повні поля й приклад надсилання чекліста

6. Новий Widget API ботів і тимчасові відповіді

Флоу: capabilities → ізольований renderer → get_widget_public_data лише для видимого віджета з watchPublicData, з урахуванням poll_period. Натискання → get_widget_query_answer з base64 data; дію автоматично не повторювати.

Bot-only: edit_message_widget_data, edit_inline_message_widget_data, edit_widget_data, answer_widget_query. Події updateNewWidgetQuery, updateNewInlineWidgetQuery, updateNewWidgetCopyQuery зберігають нативні поля.

updateMessageEphemeralContent оновлює окремий тимчасовий стан; null його очищує. Закриття — delete_message_ephemeral_content. Renderer потрібно реалізувати на фронті; wallet/signing не підтримані.

Widget API, ліміти й renderer · Повний live envelope і reducer

7. Назви файлів та метадані аудіо

В upload передавати початковий filename, у send — media.file_name для документів, аудіо й відео. Backend зберігає його окремо від технічного ключа; вирізати хеші на фронті не потрібно.

Історія аудіо повертає title, performer, duration, MIME та file references. Використовувати їх після reload так само, як у live; джерело плеєра — через чинний media flow.

Повний контракт назв та аудіо

8. Закріплені повідомлення, онлайн, «пише…», учасники

open_dialog з center_message_id враховує pinned_limit. Приймати звичайні pinned_message, зокрема після pagination_setup; повторний tail-запит не потрібний.

updateUserStatus та updateChatAction застосовувати для всіх підписаних акаунтів, незалежно від відкритого чату. Typing очищувати за cancel/timeout.

get_chat_profile оновлює кількість учасників; get_chats може уточнити її фоновим update. Застосовувати member_count з урахуванням revision/generation, без обходу всіх учасників.

Повний флоу стану діалогу

9. Автоматичний апгрейд basic group

Для slow mode, username, history visibility, forum, hidden members і підписів повідомлень backend за потреби мігрує групу. Відповідь зберігає client_request_id та додає result.chat_id, result.supergroup_id.

Флоу: нові ID → переключити діалог і ключі стану на супергрупу. Перевіряти ID також у <action>_error: налаштування може не застосуватися після успішної незворотної міграції. Старий ID для цієї операції більше не використовувати.

Усі шість екшенів, відповіді й помилки

10. Аватари всіх акаунтів без масового open_client

У allUserbotsInCompany / allUserbotsInUser запитувати profilePhotoUrl, profilePhotoRemoteId, profilePhotoUniqueId, profilePhotoMinithumbnail. Minithumbnail — base64 JPEG.

Флоу: список → URL або placeholder → інвалідація кешу при зміні photo ID. refresh_self_profile може спершу повернути profile_photo_pending_download:true; для запитувача фото — через media flow, збережений URL — у наступному GraphQL-запиті.

GraphQL-поля, refresh і кешування

11. CRM більше не додає користувача в контакти

Флоу: «Додати в CRM» → лише createLead з ідентичністю або наявним clientId. Прибрати супутні createClient, import/add-contact виклики.

Backend перевикористовує наявну особу; нова CRM-only особа не з’являється в allClients. Явне «Додати контакт» через createClient використовує ту саму особу без дубля.

Повний GraphQL-флоу CRM і контактів

12. Окремі 403/404 та блокування дубля акаунта

GraphQL user(id): errors[].extensions.code/status розрізняють NOT_FOUND/404 і FORBIDDEN/403. Окремі тексти: «Користувача не знайдено» та «У вас немає дозволу на перегляд цієї сторінки».

Auth WS: error з DUPLICATE_TELEGRAM_ACCOUNT, conflict:duplicate_phone, terminal:true, is_authenticated:false завершує авторизацію. Не активувати дублікат; оновити список. Номер може бути зайнятий поза поточною компанією; текст має скеровувати до власника номера.

Коди, тексти й refresh-конфлікт · Повний auth flow

13. Активні сеанси: поточний пристрій більше не губиться

get_active_sessions зберігає сеанси з ID "0" і від’ємними ID. current_session / current_session_id відповідають нативному is_current; other_sessions не містить поточного пристрою. ID повертаються рядками без втрати точності int64.

Флоу: показати поточний сеанс за is_current → terminate_all_other_sessions → повторний get_active_sessions. Завершення інших — одним викликом TDLib; terminate_session і set_session_settings також підтримують знакові ID.

Повний контракт, JSON та обробка ID

14. Підпис альбому в прев’ю списку чатів

Коли останній елемент альбому має порожній content.caption, backend додає last_message.caption (formattedText з text/entities) з іншого елемента того самого альбому. ID і мініатюра залишаються від останнього повідомлення.

Флоу: показати список одразу → застосувати звичайний chat_list_update, якщо підпис дочитано у фоні. Наявний fallback на last_message.caption працює без змін фронтенду; окремі history-запити не потрібні. Для альбому без підпису та одиночного фото поведінка збережена.

Повний контракт підпису альбому

15. Онлайн відкритого акаунта та повний sendChatAction

open_client вмикає онлайн для доданого акаунта; is_online:false залишає фонове відкриття тихим. Екшен set_online перемикає foreground intent поточного вікна; закриття вікна прибирає його presence, інші активні вікна зберігають акаунт онлайн.

send_chat_action підтримує всі 15 ChatAction: текст, запис, upload із progress, вибір стікера/локації/контакту, гру, animated emoji та cancel. Є всі 4 MessageTopic і business_connection_id. Нативну дію передавати у chat_action, скасування — null або chatActionCancel.

Флоу: visibility → set_online; фактичне введення → chatActionTyping приблизно раз на 4 с; пауза/відправлення/зміна діалогу → cancel. Фронту потрібно підключити ці виклики до редактора; бекенд не отримує чернетку автоматично. Прострочені transient-дії не відтворюються.

Повний контракт: усі типи, поля, JSON і frontend flow

16. Стікери, custom emoji та GIF: єдиний контракт TDLib

· зміна контракту без підтримки старих alias-ів

Picker-команди приймають native-параметри й повертають native-об’єкти TDLib. У metadata-відповідях читати sets, stickers, animations, results та emoji_keywords. Проміжних items/count/pagination/download DTO й агрегованих груп наборів більше немає. Окремий get_custom_emoji_media залишається командою доставки asset через media_ready, а не запитом native-метаданих.

Що замінити у фронті

ВидаленоВикористовуватиЯк читати результат
get_stickers_packget_installed_sticker_sets, get_trending_sticker_sets, search_sticker_sets; вміст — get_sticker_setresult.sets; у відкритому наборі — result.stickers
get_saved_gifs, get_user_gifsget_saved_animationsresult.animations
add_saved_gifadd_saved_animationresult:{"@type":"ok"}
remove_saved_gif, delete_saved_gif, delete_saved_animationremove_saved_animationresult:{"@type":"ok"}
search_animationssearch_gifs з query та offsetresult.results, result.next_offset

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

Канонічні action

Кожен запит також містить userbot_id. Нижче — поля самого action; поле, якого немає в його контракті, спричиняє <action>_error.

ActionПараметриNative-результат
get_installed_sticker_setssticker_typestickerSets{total_count,sets} — весь список metadata встановлених наборів
get_sticker_setset_idstickerSet, зокрема id та stickers
search_sticker_setname, ignore_cache (типово false)stickerSet — набір за назвою з addstickers/addemoji
get_archived_sticker_setssticker_type, offset_sticker_set_id, limitstickerSets{total_count,sets}
get_trending_sticker_setssticker_type, offset, limittrendingStickerSets{total_count,sets,is_premium}
search_sticker_setssticker_type, querystickerSets{total_count,sets}
change_sticker_setset_id, is_installed, is_archivedok; тип набору визначається за ID
reorder_installed_sticker_setssticker_type, sticker_set_idsok
get_favorite_stickersНемаєstickers{stickers}
add_favorite_stickersticker:InputFileok
remove_favorite_stickersticker:InputFileok
get_recent_stickersis_attachedstickers{stickers}
remove_recent_stickeris_attached, sticker:InputFileok
clear_recent_stickersis_attachedok
get_stickerssticker_type, query, chat_id, limitstickers{stickers} — підказки за емодзі або префіксом слова
search_stickerssticker_type, emojis, query, input_language_codes, offset, limitstickers{stickers}
get_emoji_categoriestype:EmojiCategoryType або nullemojiCategories{categories}; icon — native sticker
search_emojistext, input_language_codesemojiKeywords{emoji_keywords} — звичайні емодзі та їхні ключові слова
get_saved_animationsНемаєanimations{animations}
add_saved_animationanimation:InputFileok
remove_saved_animationanimation:InputFileok
search_gifsquery, offsetinlineQueryResults{results,next_offset,...} через getInlineQueryResults

Флоу відкриття picker і пагінації

  1. Відкрити control WS /ws/chats/, виконати open_client для потрібних акаунтів і дочекатися open_client_ready. Стан picker зберігати окремо для кожного акаунта й типу стікерів.
  2. Прочитати встановлені набори через get_installed_sticker_sets окремо для regular і custom emoji. Використовувати sets[].covers для обкладинок. Повний get_sticker_set викликати при відкритті конкретного набору.
  3. Для посилання t.me/addstickers/<name> або t.me/addemoji/<name> викликати search_sticker_set з name з посилання; відповідь уже містить повний набір. ignore_cache:true запитує оновлення набору в Telegram.
  4. Обрані, недавні та збережені GIF читати відповідними action. Новому логічному запиту давати новий client_request_id; відповідь застосовувати лише до її акаунта та актуального пошуку/вкладки.
  5. Встановлені набори, обрані, недавні та saved animations не мають штучних limit/offset. search_sticker_sets також не приймає offset/limit.
  6. Архів починати з offset_sticker_set_id:"0"; наступний cursor — sets[-1].id. Порожня сторінка завершує читання. Trending має числові offset/limit, його total_count приблизний. Для обох limit — до 100.
  7. У search_stickers використовувати його native offset/limit (limit 0–100). Підказки custom emoji — get_stickers зі StickerTypeCustomEmoji та chat_id потрібного чату.
{"action":"get_installed_sticker_sets","userbot_id":183,"sticker_type":{"@type":"stickerTypeCustomEmoji"},"client_request_id":"installed-emoji-1"}
{"action":"get_sticker_set","userbot_id":183,"set_id":"9007199254740993","client_request_id":"set-1"}
{"action":"search_sticker_set","userbot_id":183,"name":"Animals","ignore_cache":false,"client_request_id":"set-link-1"}
{"action":"get_saved_animations","userbot_id":183,"client_request_id":"saved-1"}

Приклад порожнього native-списку у звичайному envelope:

{"type":"chat_update","userbot_id":183,"payload":{"userbot_id":183,"type":"get_saved_animations","client_request_id":"saved-1","result":{"@type":"animations","animations":[]}}}

Медіа, custom emoji та premium-ефект

Підключити /ws/chats/media/ і надіслати open_media_stream з control_ws_connection_id поточного control-сокета та userbot_ids. Завантаження запускати через control WS; ресурс чекати як media_ready на медіа-WS.

{"action":"open_media_stream","control_ws_connection_id":"CONTROL_WS_ID","userbot_ids":[183]}
{"action":"download_file","userbot_id":183,"file_id":123,"remote_id":"REMOTE_ID","source":"dialogs","extra":{"kind":"sticker","set_id":"9007199254740993"}}
{"action":"get_custom_emoji_media","userbot_id":183,"custom_emoji_ids":["5393021912655030923"],"request_id":"emoji-visible-1"}

Зміни наборів, обраних і saved GIF

Мутації передавати з явними native-полями та стабільним command_id або client_request_id. Успіх повертає result:{"@type":"ok"}; після нього перечитати відповідний список. Для наборів emoji використовувати ті самі action: у reorder передати StickerTypeCustomEmoji; у change тип визначається за set_id, додаткового поля sticker_type немає.

{"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 через налаштованого Telegram GIF-бота. Порожній query запитує його початкову добірку. Результати — result.results, animation у results[].animation, файл — у results[].animation.animation. Передавати opaque next_offset як наступний offset; при зміні query починати з offset:"". Поля q/limit та додаткового is_trending немає.

Оновлення з телефону без перезавантаження

На підписаному control-сокеті приймати native-події незалежно від відкритого діалогу. Для акаунта з події інвалідувати відповідний UI-список і перечитати його; подія передає ID, а не готовий відрендерений список. Backend читає актуальний state TDLib без окремого Redis-кешу списків.

{"type":"chat_update","userbot_id":183,"payload":{"@type":"updateSavedAnimations","type":"updateSavedAnimations","userbot_id":183,"animation_ids":[123]}}

Усі action мають <action>_error з текстом error. Зайві поля відхиляються з payload.code:"invalid_picker_request"; native-помилки можуть містити payload.result.error_code, timeout та outcome_unknown. При невідомому результаті мутації спершу перечитати фактичний стан. Повтор доставки — з тим самим ID; автоматично створювати новий ID для повторної мутації не можна.

Повний native-контракт, типи параметрів і media flow · Каталог picker-action