Дзвінки

Контракт фронтенду · telegram_calls_v1 · TDLib 1.8.68

Готовність інтеграції: backend-контракт реалізовано; публічне ввімкнення потребує розгортання coordinator/worker та browser TURN. Кнопки в UI вмикайте за runtime capabilities і правами користувача. Наявність методу в каталозі не означає, що двигун доступний або користувачу дозволена дія.

1. Підключення та стан акаунта

Відкрийте wss://API/ws/calls/ із чинною HttpOnly session cookie; Origin має входити в серверний allowlist. Token у URL не передавати. Це окремий socket для дзвінків; існуючі dialog/media WS лишаються окремими. Один socket працює з одним userbot_id.

{"event":"hello","protocol":"telegram_calls_v1"}

Після hello надішліть підписку (IDs нижче — приклади):

{"action":"subscribe","userbot_id":216,"request_id":"subscribe-1","params":{}}

Відповідь має event: "result", той самий request_id, верхньорівневу generation та result: {capabilities, state, revision}. state містить calls, group_calls, gap, controller_busy. Це snapshot, а не архів дзвінків.

Поле capabilitiesЯк використовувати
compatible, tdlib_version, schema_commitПеревірка відповідності TDLib контракту. При несумісності не починати дзвінок.
methodsКаталог native методів; містить також server-only методи. Це не список виданих користувачу дозволів.
media.availableЯкщо false — медіасервіс недоступний; може бути reason: "media_service_unavailable". Не запускати WebRTC/call create.
media.private, video_chat, conference, rtmp_receiveЧитати всередині media, коли available=true. Зашифровані конференції потребують окремого ввімкнення на сервері.
media.max_remote_video, browser_turn_requiredДо 8 video slots; браузер має використовувати TURN relay.

Усі наступні запити містять отриману generation. request_id — рядок 1–128 символів: нове значення на нову логічну дію, те саме значення й payload лише для повтору тієї самої дії в тій самій сесії.

{"action":"state","userbot_id":216,"generation":"G","request_id":"state-1","params":{}}
{"action":"media.state","userbot_id":216,"generation":"G","request_id":"media-state-1","params":{}}

state читає Telegram snapshot; media.state читає стан поточного медіаз’єднання.

{"event":"result","request_id":"media-state-1","generation":"G","result":{
  "state":"connected","call_id":17,"group_call_id":null,
  "muted":false,"video":true,"screen":false,"screen_state":"idle"
}}

Без власної media session відповідь може бути лише {"state":"idle"}; решту полів вважайте необов’язковими. Один controller на акаунт: інша вкладка/оператор отримує call_control_busy. Claim/token і heartbeat керує backend; UI не створює controller token.

2. Вихідний приватний дзвінок

  1. subscribe + capabilities
  2. Дозвіл мікрофона / камери
  3. WebRTC offer → media.open
  4. Застосувати answer
  5. media.start → ringing
  6. Telegram + WebRTC connected
  1. Після натискання користувачем кнопки викличте getUserMedia. Відмова browser permission не повинна створювати Telegram-дзвінок.
  2. Створіть RTCPeerConnection із виданою вашим оточенням TURN-конфігурацією та iceTransportPolicy: "relay". Цей API не видає TURN credentials. Узгодьте їх із конфігурацією backend. SOCKS5 Telegram-акаунта не є browser TURN.
  3. Додайте microphone transceiver sendrecv, camera/screen transceivers за потреби та receive-only video slots. Усього до 8 video transceivers для повернення відео; camera/screen теж займають місце в цьому наборі.
  4. Зробіть offer і дочекайтеся завершення ICE gathering. Trickle ICE та повторна negotiation в поточній media session не підтримуються. MID беріть із transceiver після setLocalDescription, не припускайте, що це завжди 0/1.
  5. Викличте media.open, застосуйте result.sdp і result.type як remote description.
  6. Викличте media.start. result.id — ID приватного дзвінка; це ще не підтвердження відповіді співрозмовника.
  7. Опитуйте media.state раз на 1–2 секунди. Показуйте «З’єднано», коли одночасно result.state === "connected" та pc.connectionState === "connected".
{"action":"media.open","userbot_id":216,"generation":"G","request_id":"open-1","params":{
  "sdp":"BROWSER_OFFER_SDP","sources":{"0":"microphone","1":"camera"}
}}
{"action":"media.start","userbot_id":216,"generation":"G","request_id":"start-1","params":{
  "user_id":12345,"is_video":true
}}

sources — MID → device, до одного track кожного типу: microphone, camera, screen, speaker (аудіо демонстрації екрана). Audio й video типи track мають відповідати device; напрямок source у browser offer має бути sendonly або sendrecv.

{"event":"result","request_id":"open-1","generation":"G","result":{
  "type":"answer","sdp":"BROWSER_ANSWER_SDP",
  "tracks":[{"mid":"0","kind":"audio"},{"mid":"1","kind":"video","slot":0}]
}}

Прив’язуйте remote tracks за MID із result.tracks, а не за порядком подій ontrack. Remote audio — один серверний мікс; приватне remote video використовує slot 0. Якщо браузер блокує autoplay, показуйте кнопку відтворення; помилка autoplay не означає невдалий Telegram call.

result.tracks містить лише MID, на яких браузер погодив приймання медіа (recvonly або sendrecv у його offer). Камера чи екран із sendonly не займають return slot. Наприклад, після microphone MID 0, sendonly camera MID 1 і screen MID 2 перший recvonly video MID 3 відповідає {"mid":"3","kind":"video","slot":0}.

SDP у media.open належить тільки browser ↔ server WebRTC. Telegram signaling, encryption keys, protocol layers і join payload залишаються на сервері. Не записуйте SDP у логи/localStorage.

3. Вхідний дзвінок і завершення

updateCall із is_outgoing=false та callStatePending відкриває incoming UI. На «Прийняти»: browser permissions → media.open → media.accept. На «Відхилити» достатньо media.reject.

{"action":"media.accept","userbot_id":216,"generation":"G","request_id":"accept-1","params":{"call_id":17}}
{"action":"media.reject","userbot_id":216,"generation":"G","request_id":"reject-1","params":{"call_id":17}}

Це альтернативні дії; не надсилайте обидві. Якщо дзвінок уже прийнятий/завершений, сервер поверне call_not_ringing; закрийте incoming dialog без запуску вихідного дзвінка.

Дія UIЗапит і локальна дія
Завершити / вийтиmedia.hangup {} завершує поточний приватний дзвінок або залишає груповий. Browser media session може використовуватися для наступного виклику.
Закрити панель / logout / змінити акаунтmedia.close {}, зупинити всі локальні tracks, pc.close(), закрити socket, очистити стан. Для іншого userbot створити новий socket.
Завершити груповий для всіхendGroupCall {"group_call_id":8}, лише за відповідних прав і явного підтвердження користувачем.

Не переносіть media session між вкладками через localStorage. Gateway підтримує heartbeat кожні 15 секунд; втрата browser session покривається media grace 35 секунд і controller lease 60 секунд.

4. Конференції, відеочати й live story

Конференція не прив’язана до чату; video chat належить групі/каналу. Не замінюйте createVideoChat на createGroupCall: це різні сценарії.

Зашифрована конференція

Потрібне capabilities.media.conference=true. Після media.open створіть конференцію або приєднайтеся через typed InputGroupCall:

{"action":"media.create_conference","userbot_id":216,"generation":"G","request_id":"conference-1","params":{
  "is_muted":false,"is_my_video_enabled":false
}}
{"action":"media.join_conference","userbot_id":216,"generation":"G","request_id":"join-1","params":{
  "input_group_call":{"@type":"inputGroupCallLink","link":"INVITE_LINK"},
  "is_muted":true,"is_my_video_enabled":false
}}

Обидві дії повертають {"group_call_id":8}. Для запрошення через повідомлення використовуйте inputGroupCallMessage з chat_id та message_id; відмова — declineGroupCallInvitation.

{"action":"inviteGroupCallParticipant","userbot_id":216,"generation":"G","request_id":"invite-1","params":{
  "group_call_id":8,"user_id":12345,"is_video":false
}}

Перевіряйте result.@type: inviteGroupCallParticipantResultSuccess, …UserPrivacyRestricted, …UserAlreadyParticipant або …UserWasBanned. Навіть успішне запрошення ще не означає, що учасник приєднався.

Відеочат групи/каналу

  1. За потреби створити через createVideoChat {chat_id, title, start_date, is_rtmp_stream}. start_date: 0 — без запланованого часу. Для запланованого — start notification і startScheduledVideoChat.
  2. Отримати identity через getVideoChatAvailableParticipants {chat_id}.
  3. Після media.open виконати media.join_video_chat. Не генерувати власні join parameters.
{"action":"media.join_video_chat","userbot_id":216,"generation":"G","request_id":"video-chat-1","params":{
  "group_call_id":8,"participant_id":null,"invite_hash":"",
  "is_muted":true,"is_my_video_enabled":false
}}
{"action":"media.join_live_story","userbot_id":216,"generation":"G","request_id":"story-1","params":{
  "group_call_id":9,"is_muted":true,"is_my_video_enabled":false
}}

Coordinator сам робить getGroupCall для активації participant updates і початковий loadGroupCallParticipants до 100 учасників (крім live story). Далі UI завантажує сторінки до 100, поки loaded_all_participants=false. Зберігайте учасників за participant_id; order: "0" прибирає учасника зі списку.

Кнопки модерації залежать і від бізнес-дозволів, і від Telegram flags: is_owned, can_be_managed, can_enable_video, participant can_be_muted_*/can_be_unmuted_*. При need_rejoin=true запропонуйте явний повторний join.

RTMP, recording, повідомлення й Stars

RTMP/listener працює receive-only. Для транслятора використовуються get/replaceVideoChatRtmpUrl або get/replaceLiveStoryRtmpUrl; stream_key є секретом і доступний лише з правами керування. Це не URL для браузерного програвача. Recording — окремі start/endGroupCallRecording із явною дією користувача.

Групові повідомлення: sendGroupCallMessage. Для платних live-story дій показуйте суму й отримуйте згоду; pending reactions мають окремі commit/remove. Не повторюйте платіжну команду автоматично після timeout.

5. Мікрофон, камера, екран і remote video

{"action":"media.mute","userbot_id":216,"generation":"G","request_id":"mute-1","params":{"muted":true}}
{"action":"media.camera","userbot_id":216,"generation":"G","request_id":"camera-1","params":{"enabled":true}}
{"action":"media.screen_share","userbot_id":216,"generation":"G","request_id":"screen-1","params":{"enabled":true}}
{"action":"media.select_video","userbot_id":216,"generation":"G","request_id":"select-1","params":{
  "participant_id":{"@type":"messageSenderUser","user_id":12345},"source":"camera","slot":0
}}

6. Каталог actions

Таблиці параметрів будуються з Python-контракту й pinned TDLib schema під час рендерингу сторінки. Усі поля обов’язкові; позначка null означає допустиме null, а не можливість пропустити ключ. Порожні параметри передавайте як {}.

Media lifecycle · 18 actions

ActionParamsПризначення / result
media.prepare
  • {}

Result:
media.runtime
  • {}

Result:
media.open
  • sdp: string
  • sources: trackMap
Узгодити browser WebRTC до дзвінка. Після завершеного дзвінка новий offer замінює попередній idle bridge; активний дзвінок не перехоплюється.
Result: sdp, type="answer", tracks[]
media.start
  • user_id: int53
  • is_video: Bool
Почати приватний аудіо/відеодзвінок.
Result: CallId: id
media.accept
  • call_id: int32
Прийняти приватний вхідний дзвінок після media.open.
Result: call_id
media.reject
  • call_id: int32
Відхилити вхідний дзвінок без доступу до мікрофона.
Result: Ok
media.join_video_chat
  • group_call_id: int32
  • participant_id: MessageSender або null
  • invite_hash: string
  • is_muted: Bool
  • is_my_video_enabled: Bool
Приєднатися до відеочату групи/каналу.
Result: group_call_id
media.join_live_story
  • group_call_id: int32
  • is_muted: Bool
  • is_my_video_enabled: Bool
Приєднатися до live story.
Result: group_call_id
media.join_conference
  • input_group_call: InputGroupCall
  • is_muted: Bool
  • is_my_video_enabled: Bool
Приєднатися до зашифрованої конференції.
Result: group_call_id
media.create_conference
  • is_muted: Bool
  • is_my_video_enabled: Bool
Створити зашифровану конференцію і приєднатися.
Result: group_call_id
media.mute
  • muted: Bool
Керувати власним мікрофоном у поточному дзвінку.
Result: ok: true
media.camera
  • enabled: Bool
Увімкнути/вимкнути узгоджений camera track.
Result: ok: true
media.screen_share
  • enabled: Bool
Почати/зупинити узгоджений screen track.
Result: ok: true
media.select_video
  • participant_id: MessageSender
  • source: string
  • slot: int32
Прив’язати camera/screen учасника до receive slot 0–7.
Result: slot, participant_id, source
media.hangup
  • {}
Завершити приватний дзвінок або вийти з групового.
Result: ok: true
media.close
  • {}
Закрити media session і звільнити керування акаунтом.
Result: closed: true; idle, якщо сесії немає
media.state
  • {}
Отримати стан медіасесії, камери, мікрофона й екрана.
Result: state, call_id, group_call_id, muted, video, screen, screen_state
media.heartbeat
  • {}
Підтримка сесії; gateway надсилає автоматично.
Result: Як media.state; idle, якщо сесії немає

subscribe і state — окремі control actions з params {}. media.control — внутрішній wrapper backend: frontend передає native method name безпосередньо як action.

Native TDLib · 61 методів

Позначка «Лише сервер» означає відмову engine_action_required при прямому виклику з браузера. Використовуйте відповідний media action. Native result проходить редагування секретних engine-полів перед видачею UI.

ActionParamsTDLib resultВиклик
createCall
  • user_id: int53
  • protocol: callProtocol
  • is_video: Bool
CallId Лише сервер
acceptCall
  • call_id: int32
  • protocol: callProtocol
Ok Лише сервер
sendCallSignalingData
  • call_id: int32
  • data: bytes
Ok Лише сервер
discardCall
  • call_id: int32
  • is_disconnected: Bool
  • invite_link: string
  • duration: int32
  • is_video: Bool
  • connection_id: int64
Ok Лише сервер
sendCallRating
  • call_id: InputCall
  • rating: int32
  • comment: string
  • problems: vector<CallProblem>
Ok Frontend WS
Дія через controller
sendCallDebugInformation
  • call_id: InputCall
  • debug_information: string
Ok Frontend WS
Дія через controller
sendCallLog
  • call_id: InputCall
  • log_data: bytes (base64)
Ok Frontend WS
Дія через controller
getVideoChatAvailableParticipants
  • chat_id: int53
MessageSenders Frontend WS
Читання
setVideoChatDefaultParticipant
  • chat_id: int53
  • default_participant_id: MessageSender
Ok Frontend WS
Дія через controller
createVideoChat
  • chat_id: int53
  • title: string
  • start_date: int32
  • is_rtmp_stream: Bool
GroupCallId Frontend WS
Дія через controller
createGroupCall
  • join_parameters: groupCallJoinParameters або null
GroupCallInfo Лише сервер
getVideoChatRtmpUrl
  • chat_id: int53
RtmpUrl Frontend WS
Читання
replaceVideoChatRtmpUrl
  • chat_id: int53
RtmpUrl Frontend WS
Дія через controller
getLiveStoryRtmpUrl
  • chat_id: int53
RtmpUrl Frontend WS
Читання
replaceLiveStoryRtmpUrl
  • chat_id: int53
RtmpUrl Frontend WS
Дія через controller
getGroupCall
  • group_call_id: int32
GroupCall Frontend WS
Читання
startScheduledVideoChat
  • group_call_id: int32
Ok Frontend WS
Дія через controller
toggleVideoChatEnabledStartNotification
  • group_call_id: int32
  • enabled_start_notification: Bool
Ok Frontend WS
Дія через controller
joinGroupCall
  • input_group_call: InputGroupCall
  • join_parameters: groupCallJoinParameters
GroupCallInfo Лише сервер
joinVideoChat
  • group_call_id: int32
  • participant_id: MessageSender або null
  • join_parameters: groupCallJoinParameters
  • invite_hash: string
Text Лише сервер
joinLiveStory
  • group_call_id: int32
  • join_parameters: groupCallJoinParameters
Text Лише сервер
startGroupCallScreenSharing
  • group_call_id: int32
  • audio_source_id: int32
  • payload: string
Text Лише сервер
toggleGroupCallScreenSharingIsPaused
  • group_call_id: int32
  • is_paused: Bool
Ok Frontend WS
Дія через controller
endGroupCallScreenSharing
  • group_call_id: int32
Ok Лише сервер
setVideoChatTitle
  • group_call_id: int32
  • title: string
Ok Frontend WS
Дія через controller
toggleVideoChatMuteNewParticipants
  • group_call_id: int32
  • mute_new_participants: Bool
Ok Frontend WS
Дія через controller
toggleGroupCallAreMessagesAllowed
  • group_call_id: int32
  • are_messages_allowed: Bool
Ok Frontend WS
Дія через controller
getLiveStoryStreamer
  • group_call_id: int32
GroupCallParticipant Frontend WS
Читання
getLiveStoryAvailableMessageSenders
  • group_call_id: int32
ChatMessageSenders Frontend WS
Читання
setLiveStoryMessageSender
  • group_call_id: int32
  • message_sender_id: MessageSender
Ok Frontend WS
Дія через controller
sendGroupCallMessage
  • group_call_id: int32
  • text: formattedText
  • paid_message_star_count: int53
Ok Frontend WS
Дія через controller
addPendingLiveStoryReaction
  • group_call_id: int32
  • star_count: int53
Ok Frontend WS
Дія через controller
commitPendingLiveStoryReactions
  • group_call_id: int32
Ok Frontend WS
Дія через controller
removePendingLiveStoryReactions
  • group_call_id: int32
Ok Frontend WS
Дія через controller
deleteGroupCallMessages
  • group_call_id: int32
  • message_ids: vector<int32>
  • report_spam: Bool
Ok Frontend WS
Дія через controller
deleteGroupCallMessagesBySender
  • group_call_id: int32
  • sender_id: MessageSender
  • report_spam: Bool
Ok Frontend WS
Дія через controller
getLiveStoryTopDonors
  • group_call_id: int32
LiveStoryDonors Frontend WS
Читання
inviteGroupCallParticipant
  • group_call_id: int32
  • user_id: int53
  • is_video: Bool
InviteGroupCallParticipantResult Frontend WS
Дія через controller
declineGroupCallInvitation
  • chat_id: int53
  • message_id: int53
Ok Frontend WS
Дія через controller
banGroupCallParticipants
  • group_call_id: int32
  • user_ids: vector<int64>
Ok Frontend WS
Дія через controller
inviteVideoChatParticipants
  • group_call_id: int32
  • user_ids: vector<int53>
Ok Frontend WS
Дія через controller
startGroupCallRecording
  • group_call_id: int32
  • title: string
  • record_video: Bool
  • use_portrait_orientation: Bool
Ok Frontend WS
Дія через controller
endGroupCallRecording
  • group_call_id: int32
Ok Frontend WS
Дія через controller
toggleGroupCallIsMyVideoPaused
  • group_call_id: int32
  • is_my_video_paused: Bool
Ok Frontend WS
Дія через controller
toggleGroupCallIsMyVideoEnabled
  • group_call_id: int32
  • is_my_video_enabled: Bool
Ok Frontend WS
Дія через controller
setGroupCallPaidMessageStarCount
  • group_call_id: int32
  • paid_message_star_count: int53
Ok Frontend WS
Дія через controller
setGroupCallParticipantIsSpeaking
  • group_call_id: int32
  • audio_source: int32
  • is_speaking: Bool
MessageSender Frontend WS
Дія через controller
toggleGroupCallParticipantIsMuted
  • group_call_id: int32
  • participant_id: MessageSender
  • is_muted: Bool
Ok Frontend WS
Дія через controller
setGroupCallParticipantVolumeLevel
  • group_call_id: int32
  • participant_id: MessageSender
  • volume_level: int32
Ok Frontend WS
Дія через controller
toggleGroupCallParticipantIsHandRaised
  • group_call_id: int32
  • participant_id: MessageSender
  • is_hand_raised: Bool
Ok Frontend WS
Дія через controller
getGroupCallParticipants
  • input_group_call: InputGroupCall
  • limit: int32
GroupCallParticipants Frontend WS
Читання
loadGroupCallParticipants
  • group_call_id: int32
  • limit: int32
Ok Frontend WS
Дія через controller
leaveGroupCall
  • group_call_id: int32
Ok Frontend WS
Дія через controller
endGroupCall
  • group_call_id: int32
Ok Frontend WS
Дія через controller
getGroupCallStreams
  • group_call_id: int32
GroupCallStreams Frontend WS
Читання
getGroupCallStreamSegment
  • group_call_id: int32
  • time_offset: int53
  • scale: int32
  • channel_id: int32
  • video_quality: GroupCallVideoQuality або null
Data Лише сервер
encryptGroupCallData
  • group_call_id: int32
  • data_channel: GroupCallDataChannel
  • data: bytes
  • unencrypted_prefix_size: int32
Data Лише сервер
decryptGroupCallData
  • group_call_id: int32
  • participant_id: MessageSender
  • data_channel: GroupCallDataChannel або null
  • data: bytes
Data Лише сервер
searchCallMessages
  • offset: string
  • limit: int32
  • only_missed: Bool
FoundMessages Frontend WS
Читання

7. Події, revision і UI state

Live updates мають update на верхньому рівні, без event: "result". Відповіді на команди співвідносьте за request_id; updates — за account + generation + revision.

{"protocol":"telegram_calls_v1","userbot_id":216,"generation":"G","revision":12,"gap":false,
 "update":{"@type":"updateCall","call":{"id":17,"user_id":12345,"is_outgoing":false,"is_video":false,
   "state":{"@type":"callStatePending","is_created":true,"is_received":true}}}}
Telegram stateUI
callStatePendingВхідний/вихідний виклик; напрямок із is_outgoing, стадія з is_created/is_received.
callStateExchangingKeysУстановлення захищеного з’єднання.
callStateReadyПоказати emojis для звірки. Public state містить лише @type, emojis та is_group_call_supported; connected визначати разом із media.state і WebRTC.
callStateHangingUpЗавершення; вимкнути повторне прийняття.
callStateDiscarded, callStateErrorПрибрати ringing/active UI, показати причину за наявними полями, зупинити tracks при закритті сесії.

Media state також має idle, browser_connecting, telegram_connecting і native connection states. Cleanup може одразу перевести його в idle; не очікуйте гарантованої доставки кожного проміжного стану через polling.

Повний список 12 публічних update types
  • updateChatVideoChat
  • updateCall
  • updateGroupCall
  • updateGroupCallParticipant
  • updateGroupCallParticipants
  • updateGroupCallVerificationState
  • updateNewGroupCallMessage
  • updateNewGroupCallPaidReaction
  • updateGroupCallMessageSendFailed
  • updateGroupCallMessagesDeleted
  • updateLiveStoryTopDonors
  • updateGroupCallMessageLevels

updateNewCallSignalingData лишається на сервері. Через приховані signaling updates revision може перескочити: орієнтуйтеся на серверний gap. Старі revisions і generation ігноруйте.

При gap=true синхронізуйте snapshot; медіа починайте новою сесією після явної дії користувача. Після зміни owner закрийте старий PC/socket, підпишіться заново. Автоматично повторювати create/accept або платні дії не можна.

8. Дозволи й бізнес-логіка

Потрібні активне членство в компанії акаунта, tg_client.can_use_messenger, account scope (own / peers / subordinates / all) і відповідні call permissions. Права беруться з посади; якщо посади немає — з ролі. Порожня посада не успадковує права ролі. Власник компанії має owner bypass лише як активний учасник.

Permission (tg_client)Що дозволяє
calls_viewПідписка, snapshot, читання історії й станів. Сам по собі не дає controller/media.open.
calls_privateПриватні start/accept/reject/hangup, rating; разом із calls_view.
calls_groupГрупова участь, створення конференції, запрошення, звичайні повідомлення.
calls_manageСтворення video chat, управління груповим дзвінком, end для всіх, RTMP credentials; для змін також потрібен calls_group.
calls_recordЗапис; додатково до calls_group + calls_manage.
calls_diagnosticsВідправлення debug/log у Telegram за явною дією користувача.
calls_paymentsВитрата Stars, додатково до group access. Commit pending reactions теж вимагає цього дозволу.

Backend повторно перевіряє права та тип активного дзвінка. Не довіряйте лише прихованій кнопці. Telegram окремо перевіряє свої admin rights: дозвіл посади не робить Telegram-акаунт адміністратором чату.

9. Помилки, timeout і reconnect

{"event":"error","request_id":"start-1","error":{
  "code":"call_control_busy","message":"Another browser session controls calls on this account","retryable":false
}}
CodeРеакція фронтенду
forbidden, unauthenticatedЗупинити tracks, очистити приватний стан; повторна авторизація/перевірка доступів.
account_logged_outПотрібна авторизація Telegram-акаунта через чинний auth flow.
call_control_busyАкаунтом керує інша вкладка/оператор. Не перехоплювати керування.
owner_changed, account_changedНова WS-підписка, актуальна generation, нова media session; без автоматичного повторного дзвінка.
outcome_unknown, media_unavailable, media_error, internal_errorРезультат дії може бути невідомим. Перевірити state/snapshot; не надсилати новий create з новим request_id.
request_id_conflictОдин request_id використано для різних payload; виправити клієнтську кореляцію.
media_not_open, media_already_open, call_already_activeСинхронізувати lifecycle; не створювати другу сесію поверх чинної.
call_not_ringing, no_active_callОновити UI: виклик уже змінив стан.
participant_unavailable, video_unavailableДочекатися/оновити participant state, прибрати недоступний video slot.
proxy_changed, media_egress_unverifiedПотрібне переналаштування worker. Прямий вихід у Telegram як fallback заборонений.
tdlib_incompatible, owner_unavailableBackend не готовий до виклику; показати недоступність сервісу.
engine_action_requiredВикористати media.* замість server-only TDLib method.
tdlib_errorTelegram відхилив дію. Перевірити поточний стан і Telegram rights; не очікувати raw native error з секретними параметрами.
invalid_request, unknown_action, response_too_largeВиправити payload/зменшити сторінку; не запускати retry loop.
rate_limited, session_capacityОбмежити частоту; при вичерпанні місткості коректно закрити сесію й відкрити нову.

WS close codes: 4401 — немає авторизованої сесії; 4403 — Origin/доступ або втрачений watchdog; 4404 — feature вимкнена; 4410 — втрачена синхронізація/owner. Якщо браузер не дає close reason під час handshake, показуйте загальну помилку з’єднання.

Request deduplication діє тільки в межах поточної controller session, до 2048 дій. Після reconnect/зміни generation не вважайте попередній request_id гарантією від повторного виклику.

10. Типи й обмеження

{"action":"sendCallRating","userbot_id":216,"generation":"G","request_id":"rating-1","params":{
  "call_id":{"@type":"inputCallDiscarded","call_id":17},"rating":5,"comment":"","problems":[]
}}
Вкладені TDLib constructors і точні поля

Типи для server-only методів наведені для звірки контракту; їхня наявність не відкриває engine API фронтенду.

@typeПоляТип результату
boolFalse
  • Лише @type
Bool
boolTrue
  • Лише @type
Bool
int32
  • Лише @type
Int32
bytes
  • Лише @type
Bytes
groupCallDataChannelMain
  • Лише @type
GroupCallDataChannel
groupCallDataChannelScreenSharing
  • Лише @type
GroupCallDataChannel
messageSenderUser
  • user_id: int53
MessageSender
messageSenderChat
  • chat_id: int53
MessageSender
int53
  • Лише @type
Int53
groupCallVideoQualityThumbnail
  • Лише @type
GroupCallVideoQuality
groupCallVideoQualityMedium
  • Лише @type
GroupCallVideoQuality
groupCallVideoQualityFull
  • Лише @type
GroupCallVideoQuality
inputGroupCallLink
  • link: string
InputGroupCall
inputGroupCallMessage
  • chat_id: int53
  • message_id: int53
InputGroupCall
int64
  • Лише @type
Int64
formattedText
  • text: string
  • entities: vector<textEntity>
FormattedText
textEntity
  • offset: int32
  • length: int32
  • type: TextEntityType
TextEntity
textEntityTypeMention
  • Лише @type
TextEntityType
textEntityTypeHashtag
  • Лише @type
TextEntityType
textEntityTypeCashtag
  • Лише @type
TextEntityType
textEntityTypeBotCommand
  • Лише @type
TextEntityType
textEntityTypeUrl
  • Лише @type
TextEntityType
textEntityTypeEmailAddress
  • Лише @type
TextEntityType
textEntityTypePhoneNumber
  • Лише @type
TextEntityType
textEntityTypeBankCardNumber
  • Лише @type
TextEntityType
textEntityTypeTonAddress
  • Лише @type
TextEntityType
textEntityTypeBold
  • Лише @type
TextEntityType
textEntityTypeItalic
  • Лише @type
TextEntityType
textEntityTypeUnderline
  • Лише @type
TextEntityType
textEntityTypeStrikethrough
  • Лише @type
TextEntityType
textEntityTypeSpoiler
  • Лише @type
TextEntityType
textEntityTypeCode
  • Лише @type
TextEntityType
textEntityTypePre
  • Лише @type
TextEntityType
textEntityTypePreCode
  • language: string
TextEntityType
textEntityTypeBlockQuote
  • Лише @type
TextEntityType
textEntityTypeExpandableBlockQuote
  • Лише @type
TextEntityType
textEntityTypeTextUrl
  • url: string
TextEntityType
textEntityTypeMentionName
  • user_id: int53
TextEntityType
textEntityTypeCustomEmoji
  • custom_emoji_id: int64
TextEntityType
textEntityTypeMediaTimestamp
  • media_timestamp: int32
TextEntityType
textEntityTypeDateTime
  • unix_time: int32
  • formatting_type: DateTimeFormattingType
TextEntityType
dateTimeFormattingTypeRelative
  • Лише @type
DateTimeFormattingType
dateTimeFormattingTypeAbsolute
  • time_precision: DateTimePartPrecision
  • date_precision: DateTimePartPrecision
  • show_day_of_week: Bool
DateTimeFormattingType
dateTimePartPrecisionNone
  • Лише @type
DateTimePartPrecision
dateTimePartPrecisionShort
  • Лише @type
DateTimePartPrecision
dateTimePartPrecisionLong
  • Лише @type
DateTimePartPrecision
groupCallJoinParameters
  • audio_source_id: int32
  • payload: string
  • is_muted: Bool
  • is_my_video_enabled: Bool
GroupCallJoinParameters
inputCallDiscarded
  • call_id: int32
InputCall
inputCallFromMessage
  • chat_id: int53
  • message_id: int53
InputCall
callProblemEcho
  • Лише @type
CallProblem
callProblemNoise
  • Лише @type
CallProblem
callProblemInterruptions
  • Лише @type
CallProblem
callProblemDistortedSpeech
  • Лише @type
CallProblem
callProblemSilentLocal
  • Лише @type
CallProblem
callProblemSilentRemote
  • Лише @type
CallProblem
callProblemDropped
  • Лише @type
CallProblem
callProblemDistortedVideo
  • Лише @type
CallProblem
callProblemPixelatedVideo
  • Лише @type
CallProblem
callProtocol
  • udp_p2p: Bool
  • udp_reflector: Bool
  • min_layer: int32
  • max_layer: int32
  • library_versions: vector<string>
CallProtocol

Джерело: TDLib schema 1.8.68, commit c15d3f5a5de6e3ba5839822c451152e5e18bb700. Живими тестами перевірено private audio/video, incoming audio та encrypted group audio через account proxy. Screen sharing, RTMP/live story, recording і повний browser → Telegram маршрут із production TURN ще потребують приймальних тестів.