Дзвінки
Контракт фронтенду · 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. Вихідний приватний дзвінок
- subscribe + capabilities
- Дозвіл мікрофона / камери
- WebRTC offer → media.open
- Застосувати answer
- media.start → ringing
- Telegram + WebRTC connected
- Після натискання користувачем кнопки викличте
getUserMedia. Відмова browser permission не повинна створювати Telegram-дзвінок. - Створіть
RTCPeerConnectionіз виданою вашим оточенням TURN-конфігурацією таiceTransportPolicy: "relay". Цей API не видає TURN credentials. Узгодьте їх із конфігурацією backend. SOCKS5 Telegram-акаунта не є browser TURN. - Додайте microphone transceiver
sendrecv, camera/screen transceivers за потреби та receive-only video slots. Усього до 8 video transceivers для повернення відео; camera/screen теж займають місце в цьому наборі. - Зробіть offer і дочекайтеся завершення ICE gathering. Trickle ICE та повторна negotiation в поточній media session не підтримуються.
MID беріть із transceiver після
setLocalDescription, не припускайте, що це завжди 0/1. - Викличте
media.open, застосуйтеresult.sdpіresult.typeяк remote description. - Викличте
media.start.result.id— ID приватного дзвінка; це ще не підтвердження відповіді співрозмовника. - Опитуйте
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.
Навіть успішне запрошення ще не означає, що учасник приєднався.
Відеочат групи/каналу
- За потреби створити через
createVideoChat {chat_id, title, start_date, is_rtmp_stream}.start_date: 0— без запланованого часу. Для запланованого — start notification іstartScheduledVideoChat. - Отримати identity через
getVideoChatAvailableParticipants {chat_id}. - Після 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
}}
- Зміна пристрою —
RTCRtpSender.replaceTrack()у заздалегідь узгодженому transceiver. Якщо потрібного transceiver немає, потрібна нова media session; renegotiation API відсутній. getDisplayMediaлише з user gesture. Додайте display track до screen sender, потім media.screen_share. Для системного аудіо використовуйте speaker sender, якщо браузер його надає.displayTrack.onended→ media.screen_share з enabled=false; зупиніть і screen, і display audio tracks.screen_stateописує presentation окремо від основного call state.- У груповому дзвінку оберіть до 8 джерел через media.select_video;
source— camera або screen. Використовуйте лише slots, повернуті вmedia.open.result.tracks; 8 — верхня межа, а не кількість узгоджених потоків. Неузгоджений slot повернеinvalid_request. Заміна slot прибирає попередню native subscription. Зникнення відео чи вихід учасника очищає slot — UI теж має прибрати кадр. - Гучність учасника:
setGroupCallParticipantVolumeLevel, 1–20000 (10000 = 100%). Локальний mute і volume застосовуються до серверного міксу, включно з аудіо екрана. - Для власної камери використовуйте media.camera: raw toggleGroupCallIsMyVideoEnabled змінює Telegram state, але не замінює налаштування capture двигуна. Pause flags теж не зупиняють browser tracks самі по собі.
6. Каталог actions
Таблиці параметрів будуються з Python-контракту й pinned TDLib schema під час рендерингу сторінки.
Усі поля обов’язкові; позначка null означає допустиме null, а не можливість пропустити ключ.
Порожні параметри передавайте як {}.
Media lifecycle · 18 actions
| Action | Params | Призначення / result |
|---|---|---|
media.prepare |
|
Result: |
media.runtime |
|
Result: |
media.open |
|
Узгодити browser WebRTC до дзвінка. Після завершеного дзвінка новий offer замінює попередній idle bridge; активний дзвінок не перехоплюється. Result: sdp, type="answer", tracks[] |
media.start |
|
Почати приватний аудіо/відеодзвінок. Result: CallId: id |
media.accept |
|
Прийняти приватний вхідний дзвінок після media.open. Result: call_id |
media.reject |
|
Відхилити вхідний дзвінок без доступу до мікрофона. Result: Ok |
media.join_video_chat |
|
Приєднатися до відеочату групи/каналу. Result: group_call_id |
media.join_live_story |
|
Приєднатися до live story. Result: group_call_id |
media.join_conference |
|
Приєднатися до зашифрованої конференції. Result: group_call_id |
media.create_conference |
|
Створити зашифровану конференцію і приєднатися. Result: group_call_id |
media.mute |
|
Керувати власним мікрофоном у поточному дзвінку. Result: ok: true |
media.camera |
|
Увімкнути/вимкнути узгоджений camera track. Result: ok: true |
media.screen_share |
|
Почати/зупинити узгоджений screen track. Result: ok: true |
media.select_video |
|
Прив’язати 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.
| Action | Params | TDLib result | Виклик |
|---|---|---|---|
createCall |
|
CallId |
Лише сервер |
acceptCall |
|
Ok |
Лише сервер |
sendCallSignalingData |
|
Ok |
Лише сервер |
discardCall |
|
Ok |
Лише сервер |
sendCallRating |
|
Ok |
Frontend WS Дія через controller |
sendCallDebugInformation |
|
Ok |
Frontend WS Дія через controller |
sendCallLog |
|
Ok |
Frontend WS Дія через controller |
getVideoChatAvailableParticipants |
|
MessageSenders |
Frontend WS Читання |
setVideoChatDefaultParticipant |
|
Ok |
Frontend WS Дія через controller |
createVideoChat |
|
GroupCallId |
Frontend WS Дія через controller |
createGroupCall |
|
GroupCallInfo |
Лише сервер |
getVideoChatRtmpUrl |
|
RtmpUrl |
Frontend WS Читання |
replaceVideoChatRtmpUrl |
|
RtmpUrl |
Frontend WS Дія через controller |
getLiveStoryRtmpUrl |
|
RtmpUrl |
Frontend WS Читання |
replaceLiveStoryRtmpUrl |
|
RtmpUrl |
Frontend WS Дія через controller |
getGroupCall |
|
GroupCall |
Frontend WS Читання |
startScheduledVideoChat |
|
Ok |
Frontend WS Дія через controller |
toggleVideoChatEnabledStartNotification |
|
Ok |
Frontend WS Дія через controller |
joinGroupCall |
|
GroupCallInfo |
Лише сервер |
joinVideoChat |
|
Text |
Лише сервер |
joinLiveStory |
|
Text |
Лише сервер |
startGroupCallScreenSharing |
|
Text |
Лише сервер |
toggleGroupCallScreenSharingIsPaused |
|
Ok |
Frontend WS Дія через controller |
endGroupCallScreenSharing |
|
Ok |
Лише сервер |
setVideoChatTitle |
|
Ok |
Frontend WS Дія через controller |
toggleVideoChatMuteNewParticipants |
|
Ok |
Frontend WS Дія через controller |
toggleGroupCallAreMessagesAllowed |
|
Ok |
Frontend WS Дія через controller |
getLiveStoryStreamer |
|
GroupCallParticipant |
Frontend WS Читання |
getLiveStoryAvailableMessageSenders |
|
ChatMessageSenders |
Frontend WS Читання |
setLiveStoryMessageSender |
|
Ok |
Frontend WS Дія через controller |
sendGroupCallMessage |
|
Ok |
Frontend WS Дія через controller |
addPendingLiveStoryReaction |
|
Ok |
Frontend WS Дія через controller |
commitPendingLiveStoryReactions |
|
Ok |
Frontend WS Дія через controller |
removePendingLiveStoryReactions |
|
Ok |
Frontend WS Дія через controller |
deleteGroupCallMessages |
|
Ok |
Frontend WS Дія через controller |
deleteGroupCallMessagesBySender |
|
Ok |
Frontend WS Дія через controller |
getLiveStoryTopDonors |
|
LiveStoryDonors |
Frontend WS Читання |
inviteGroupCallParticipant |
|
InviteGroupCallParticipantResult |
Frontend WS Дія через controller |
declineGroupCallInvitation |
|
Ok |
Frontend WS Дія через controller |
banGroupCallParticipants |
|
Ok |
Frontend WS Дія через controller |
inviteVideoChatParticipants |
|
Ok |
Frontend WS Дія через controller |
getVideoChatInviteLink |
|
HttpUrl |
Frontend WS Читання |
revokeGroupCallInviteLink |
|
Ok |
Frontend WS Дія через controller |
startGroupCallRecording |
|
Ok |
Frontend WS Дія через controller |
endGroupCallRecording |
|
Ok |
Frontend WS Дія через controller |
toggleGroupCallIsMyVideoPaused |
|
Ok |
Frontend WS Дія через controller |
toggleGroupCallIsMyVideoEnabled |
|
Ok |
Frontend WS Дія через controller |
setGroupCallPaidMessageStarCount |
|
Ok |
Frontend WS Дія через controller |
setGroupCallParticipantIsSpeaking |
|
MessageSender |
Frontend WS Дія через controller |
toggleGroupCallParticipantIsMuted |
|
Ok |
Frontend WS Дія через controller |
setGroupCallParticipantVolumeLevel |
|
Ok |
Frontend WS Дія через controller |
toggleGroupCallParticipantIsHandRaised |
|
Ok |
Frontend WS Дія через controller |
getGroupCallParticipants |
|
GroupCallParticipants |
Frontend WS Читання |
loadGroupCallParticipants |
|
Ok |
Frontend WS Дія через controller |
leaveGroupCall |
|
Ok |
Frontend WS Дія через controller |
endGroupCall |
|
Ok |
Frontend WS Дія через controller |
getGroupCallStreams |
|
GroupCallStreams |
Frontend WS Читання |
getGroupCallStreamSegment |
|
Data |
Лише сервер |
encryptGroupCallData |
|
Data |
Лише сервер |
decryptGroupCallData |
|
Data |
Лише сервер |
searchCallMessages |
|
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 state | UI |
|---|---|
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
updateChatVideoChatupdateCallupdateGroupCallupdateGroupCallParticipantupdateGroupCallParticipantsupdateGroupCallVerificationStateupdateNewGroupCallMessageupdateNewGroupCallPaidReactionupdateGroupCallMessageSendFailedupdateGroupCallMessagesDeletedupdateLiveStoryTopDonorsupdateGroupCallMessageLevels
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_unavailable | Backend не готовий до виклику; показати недоступність сервісу. |
engine_action_required | Використати media.* замість server-only TDLib method. |
tdlib_error | Telegram відхилив дію. Перевірити поточний стан і 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. Типи й обмеження
int64передавайте десятковим рядком;int53/int32— JSON number. Значення IDs не переводити механічно у формат інших WS протоколів.- Typed objects обов’язково містять
@typeі всі поля відповідного constructor. Невідомі поля, методи, довільні серверні file paths відхиляються. sendCallLogприймаєlog_database64, не log_file; до 512 KiB decoded. Native call rating/debug/log використовуєInputCall, а не просто integer.- JSON packet до 768 KiB; string до 128 KiB UTF-8. Вектори до 1000 елементів; inviteVideoChatParticipants — 1–10, searchCallMessages/loadGroupCallParticipants — limit 1–100, rating — 1–5.
- Browser SDP: relay candidates лише з дозволених TURN CIDR, максимум 12 media tracks; sources map до 4 devices.
{"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 |
|
Bool |
boolTrue |
|
Bool |
int32 |
|
Int32 |
bytes |
|
Bytes |
groupCallDataChannelMain |
|
GroupCallDataChannel |
groupCallDataChannelScreenSharing |
|
GroupCallDataChannel |
messageSenderUser |
|
MessageSender |
messageSenderChat |
|
MessageSender |
int53 |
|
Int53 |
groupCallVideoQualityThumbnail |
|
GroupCallVideoQuality |
groupCallVideoQualityMedium |
|
GroupCallVideoQuality |
groupCallVideoQualityFull |
|
GroupCallVideoQuality |
inputGroupCallLink |
|
InputGroupCall |
inputGroupCallMessage |
|
InputGroupCall |
int64 |
|
Int64 |
formattedText |
|
FormattedText |
textEntity |
|
TextEntity |
textEntityTypeMention |
|
TextEntityType |
textEntityTypeHashtag |
|
TextEntityType |
textEntityTypeCashtag |
|
TextEntityType |
textEntityTypeBotCommand |
|
TextEntityType |
textEntityTypeUrl |
|
TextEntityType |
textEntityTypeEmailAddress |
|
TextEntityType |
textEntityTypePhoneNumber |
|
TextEntityType |
textEntityTypeBankCardNumber |
|
TextEntityType |
textEntityTypeTonAddress |
|
TextEntityType |
textEntityTypeBold |
|
TextEntityType |
textEntityTypeItalic |
|
TextEntityType |
textEntityTypeUnderline |
|
TextEntityType |
textEntityTypeStrikethrough |
|
TextEntityType |
textEntityTypeSpoiler |
|
TextEntityType |
textEntityTypeCode |
|
TextEntityType |
textEntityTypePre |
|
TextEntityType |
textEntityTypePreCode |
|
TextEntityType |
textEntityTypeBlockQuote |
|
TextEntityType |
textEntityTypeExpandableBlockQuote |
|
TextEntityType |
textEntityTypeTextUrl |
|
TextEntityType |
textEntityTypeMentionName |
|
TextEntityType |
textEntityTypeCustomEmoji |
|
TextEntityType |
textEntityTypeMediaTimestamp |
|
TextEntityType |
textEntityTypeDateTime |
|
TextEntityType |
dateTimeFormattingTypeRelative |
|
DateTimeFormattingType |
dateTimeFormattingTypeAbsolute |
|
DateTimeFormattingType |
dateTimePartPrecisionNone |
|
DateTimePartPrecision |
dateTimePartPrecisionShort |
|
DateTimePartPrecision |
dateTimePartPrecisionLong |
|
DateTimePartPrecision |
groupCallJoinParameters |
|
GroupCallJoinParameters |
inputCallDiscarded |
|
InputCall |
inputCallFromMessage |
|
InputCall |
callProblemEcho |
|
CallProblem |
callProblemNoise |
|
CallProblem |
callProblemInterruptions |
|
CallProblem |
callProblemDistortedSpeech |
|
CallProblem |
callProblemSilentLocal |
|
CallProblem |
callProblemSilentRemote |
|
CallProblem |
callProblemDropped |
|
CallProblem |
callProblemDistortedVideo |
|
CallProblem |
callProblemPixelatedVideo |
|
CallProblem |
callProtocol |
|
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 ще потребують приймальних тестів.