Оновлення для фронтенду
· 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 обмеження.
2. Прев’ю посилань до відправлення та в історії
Екшен: get_link_preview(text, link_preview_options?) →
result: linkPreview | null; помилка — get_link_preview_error.
Флоу: зміна посилання → debounce-запит → картка над редактором; застарілі відповіді ігнорувати.
Закриття картки → send_message / send_comment з
link_preview_options: {"@type":"linkPreviewOptions","is_disabled":true}.
В open_dialog, history та обох пошуках читати верхній link_preview;
текстове content: [] збережене. У live — нативний content.link_preview.
Фото надісланого повідомлення — через download_file за його remote ID.
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.
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 не підтримані.
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-запиті.
11. CRM більше не додає користувача в контакти
Флоу: «Додати в CRM» → лише createLead з ідентичністю або наявним
clientId. Прибрати супутні createClient, import/add-contact виклики.
Backend перевикористовує наявну особу; нова CRM-only особа не з’являється в allClients.
Явне «Додати контакт» через createClient використовує ту саму особу без дубля.
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 завершує авторизацію.
Не активувати дублікат; оновити список. Номер може бути зайнятий поза поточною компанією;
текст має скеровувати до власника номера.
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.
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 flow16. Стікери, 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_pack | get_installed_sticker_sets, get_trending_sticker_sets, search_sticker_sets; вміст — get_sticker_set | result.sets; у відкритому наборі — result.stickers |
get_saved_gifs, get_user_gifs | get_saved_animations | result.animations |
add_saved_gif | add_saved_animation | result:{"@type":"ok"} |
remove_saved_gif, delete_saved_gif, delete_saved_animation | remove_saved_animation | result:{"@type":"ok"} |
search_animations | search_gifs з query та offset | result.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_sets | sticker_type | stickerSets{total_count,sets} — весь список metadata встановлених наборів |
get_sticker_set | set_id | stickerSet, зокрема id та stickers |
search_sticker_set | name, ignore_cache (типово false) | stickerSet — набір за назвою з addstickers/addemoji |
get_archived_sticker_sets | sticker_type, offset_sticker_set_id, limit | stickerSets{total_count,sets} |
get_trending_sticker_sets | sticker_type, offset, limit | trendingStickerSets{total_count,sets,is_premium} |
search_sticker_sets | sticker_type, query | stickerSets{total_count,sets} |
change_sticker_set | set_id, is_installed, is_archived | ok; тип набору визначається за ID |
reorder_installed_sticker_sets | sticker_type, sticker_set_ids | ok |
get_favorite_stickers | Немає | stickers{stickers} |
add_favorite_sticker | sticker:InputFile | ok |
remove_favorite_sticker | sticker:InputFile | ok |
get_recent_stickers | is_attached | stickers{stickers} |
remove_recent_sticker | is_attached, sticker:InputFile | ok |
clear_recent_stickers | is_attached | ok |
get_stickers | sticker_type, query, chat_id, limit | stickers{stickers} — підказки за емодзі або префіксом слова |
search_stickers | sticker_type, emojis, query, input_language_codes, offset, limit | stickers{stickers} |
get_emoji_categories | type:EmojiCategoryType або null | emojiCategories{categories}; icon — native sticker |
search_emojis | text, input_language_codes | emojiKeywords{emoji_keywords} — звичайні емодзі та їхні ключові слова |
get_saved_animations | Немає | animations{animations} |
add_saved_animation | animation:InputFile | ok |
remove_saved_animation | animation:InputFile | ok |
search_gifs | query, offset | inlineQueryResults{results,next_offset,...} через getInlineQueryResults |
Флоу відкриття picker і пагінації
- Відкрити control WS
/ws/chats/, виконатиopen_clientдля потрібних акаунтів і дочекатисяopen_client_ready. Стан picker зберігати окремо для кожного акаунта й типу стікерів. - Прочитати встановлені набори через
get_installed_sticker_setsокремо для regular і custom emoji. Використовуватиsets[].coversдля обкладинок. Повнийget_sticker_setвикликати при відкритті конкретного набору. - Для посилання
t.me/addstickers/<name>абоt.me/addemoji/<name>викликатиsearch_sticker_setз name з посилання; відповідь уже містить повний набір.ignore_cache:trueзапитує оновлення набору в Telegram. - Обрані, недавні та збережені GIF читати відповідними action. Новому логічному запиту давати новий
client_request_id; відповідь застосовувати лише до її акаунта та актуального пошуку/вкладки. - Встановлені набори, обрані, недавні та saved animations не мають штучних limit/offset.
search_sticker_setsтакож не приймає offset/limit. - Архів починати з
offset_sticker_set_id:"0"; наступний cursor —sets[-1].id. Порожня сторінка завершує читання. Trending має числові offset/limit, його total_count приблизний. Для обох limit — до 100. - У
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]}
- Стікер: файл у
sticker.id/sticker.remote.idвсередині native sticker; для animation —animation.id/animation.remote.id. Ці посилання передавати як file_id/remote_id у чиннийdownload_file. - Набір стікера —
set_id. Custom emoji ID —full_type.custom_emoji_id. Доставку emoji замовляти лише масивомcustom_emoji_idsуget_custom_emoji_media(до 512 ID). - Ack emoji містить
result.items:[{emoji_id,set_id}]; наступнийmedia_ready.resultміститьkind:"custom_emoji",emoji_id,set_id,pathі формат. Set ID зберігається також при cache hit; невідомий набір —null. - Premium-ефект повідомлення:
full_type.premium_animation— окремий native file. Завантажити його через той самий download_file/media_ready flow. Формат брати з метаданих, а не з розширення token URL.
{"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-кешу списків.
updateInstalledStickerSets→ installed-набори та їх порядок за sticker_type.updateFavoriteStickers→ get_favorite_stickers.updateRecentStickers→ get_recent_stickers з is_attached із події.updateSavedAnimations→ get_saved_animations.updateStickerSet→ оновити відповідний набір;updateTrendingStickerSets→ відповідну trending-добірку.
{"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 для повторної мутації не можна.