tg_client WebSocket Docs: Domain Core Reference

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

1. Frontend підключається до /ws/chats/.
2. Надсилає {"action":"open_client","userbot_id":...} для старту слухача подій.
3. Надсилає команди (open_dialog, send_message, ...).
4. Consumer публікує їх у Redis канал tg_commands.
5. Listener виконує TDLib методи і публікує відповіді в tg_commands:{ws_connection_id}.
6. Live updates публікуються окремо в tg_updates:{userbot_id}, а media_ready — в tg_media:{ws_connection_id}.
7. Consumer повертає WS-події клієнту: message, dialog_end, send_message, *_error, media_ready.

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

Client Session

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

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

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

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

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

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

Channel Commands

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

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

{"action":"get_recently_opened_chats","userbot_id":1,"limit":20}

{"action":"archive_chat","userbot_id":1,"chat_id":"123"}

{"action":"unarchive_chat","userbot_id":1,"chat_id":"123"}

{"action":"pin_chat","userbot_id":1,"chat_id":"123","is_pinned":true,"chat_list":"chatListMain"}

{"action":"chat_in_folder","userbot_id":1,"chat_id":"123","chat_folder_id":2,"added":true,"removed":false,"pin":false,"unpin":false}

{"action":"create_chat_folder","userbot_id":1,"title":"Робота","icon_name":"Work","is_shareable":true,"included_chat_ids":[-1001234567890]}

{"action":"get_chats_for_chat_folder_invite_link","userbot_id":1,"chat_folder_id":2}

{"action":"get_chat_folder_invite_links","userbot_id":1,"chat_folder_id":2}

{"action":"create_chat_folder_invite_link","userbot_id":1,"chat_folder_id":2,"name":"Команда","chat_ids":[-1001234567890,-1009876543210]}

{"action":"edit_chat_folder_invite_link","userbot_id":1,"chat_folder_id":2,"invite_link":"https://t.me/addlist/abc","name":"Команда v2","chat_ids":[-1001234567890]}

{"action":"delete_chat_folder_invite_link","userbot_id":1,"chat_folder_id":2,"invite_link":"https://t.me/addlist/abc"}

{"action":"delete_chat","userbot_id":1,"chat_id":"123","revoke":true,"remove_from_chat_list":true}

{"action":"delete_channel","userbot_id":1,"chat_id":"-1001234567890","revoke":true,"remove_from_chat_list":true}

{"action":"leave_chat","userbot_id":1,"chat_id":"123"}

Для get_chats і get_recently_opened_chats бекенд повертає тільки metadata. Якщо фронту потрібне медіа, він окремо викликає download_file або get_custom_emoji_media.

Dialog Commands

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

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

{"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":"open_comments","userbot_id":1,"comments_meta":{"discussion_chat_id":"-100999000777","message_thread_id":"9001"},"limit":50}

{"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":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_global","userbot_id":1,"query":"при","limit":30}

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

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

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

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

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

Search Filters

Filter Aliases

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

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

comments_meta у message payload: discussion_chat_id — linked discussion chat, message_thread_id — thread поста, comment_count — кількість коментарів, якщо TDLib її віддає.

Message Commands

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

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

{"action":"send_message","userbot_id":1,"chat_id":"222222","text":"Cross-chat reply","reply_to":{"replyToChatId":"111111","replyToMsgId":"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":"tg/outgoing/userbot_1/chat_123456/photo/one.jpg","file_name":"one.jpg"},{"type":"video","key":"tg/outgoing/userbot_1/chat_123456/video/two.mp4","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":"tg/outgoing/userbot_1/chat_123/document/report.pdf","file_name":"report.pdf"},"protect_content":true}

{"type":"comments_access","userbot_id":1,"result":{"discussion_chat_id":"-100999000777","message_thread_id":"9001","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":"delete_messages","userbot_id":1,"chat_id":"123456","message_ids":["555","556"],"revoke":true}

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

Media Commands

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

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

{"action":"get_prem_path","userbot_id":1,"emoji_id":"5393021912655030923"}

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

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

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

Подія 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_unique_id":"AQAD...","chat_id":"-1001234567890","msg_id":"555"}}

Базові поля: file_id, path, kind. Додатково можуть приходити remote_unique_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.

Варіант 2: premium/custom emoji

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

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

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

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

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

User / Chat Profiles / Contacts

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

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

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

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

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

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

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

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

{"action":"get_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_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":"check_chat_username","userbot_id":1,"chat_id":"-1001234567890","username":"my_channel"}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Фільтри для 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 треба блокувати або ховати.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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