Документація tg_client

1. Огляд архітектури

Пакет складається з кількох горизонтальних шарів:

• Моделі описують userbot-ів і кешовані кастомні емодзі.
• _tg_utils містить конфігурацію TDLib та менеджер сесій.
• auth реалізує WebSocket-флоу для авторизації userbot-а.
• dialogs — основний стек для роботи з чатами: сервіси, обробники оновлень, лістенери та WebSocket-консюмери.

2. Структура директорій

3. Моделі Django

UserBot

• Зберігає phone, api_id, api_hash, session_path, session_str та статус is_authenticated.
• Пов'язаний із accounts.UserProfile та company.Company.
• Поля tg_nickname, username, premium оновлюються після авторизації.
• Метод save() автогенерує session_path як /app/session_accounts/<pk>_<phone>/.

CustomEmoji

• Кешує кастомні емодзі (JSON Lottie або WEBM) для повторного використання.
• Використовується TDLibHelper під час форматування тексту.

4. _tg_utils

config.py

• Визначає шлях до libtdjson.so, API_ID, API_HASH та database_encryption_key.
• DEV_MODE дозволяє жорстко задати тестові значення; у проді всі секрети тягнуться через get_secret().

session_manager.py

• SessionManager гарантує, що лише один процес працює з TDLib-сесією.
• Метод get_client() — асинхронний контекст, що блокує сесію, створює Telegram-клієнт, повертає його й потім безпечно відключає (client.stop()).
• create_new_session() ініціює клієнт для авторизації (використовується у WebSocket auth).
• check_session_health() запускає quick health-check (get_me()).
• Функція get_session_manager() забезпечує сінглтон менеджера.

5. WebSocket-авторизація (tg_client/auth)

TDLibAuthConsumer керує повним циклом логіну userbot-а:

1. start — ініціалізує SessionManager, створює TDLib-клієнт, запускає login(blocking=False).
2. send_code — передає код підтвердження (AuthorizationState.WAIT_CODE).
3. send_password — вводить 2FA (AuthorizationState.WAIT_PASSWORD).
4. Після READY витягує профіль через get_me(), оновлює UserBot, закриває сесію.

Комунікація завжди ведеться через JSON-повідомлення Channels, Redis тут не залучений.

Ендпойнт WebSocket: wss://<host>/ws/tg-auth/ (див. tg_client/routing.py).

Приклади клієнтських запитів

1. Старт авторизації:

{
  "action": "start",
  "userbot_id": 12,
  "phone": "+380955870336"
}

2. Передача одноразового коду (стає доступною після події code_required):

{
  "action": "send_code",
  "code": "12345"
}

3. Введення 2FA-пароля (коли бекенд надіслав password_required):

{
  "action": "send_password",
  "password": "my-secret"
}

Приклади відповідей сервера

{"type": "connected", "message": "WebSocket connected"}
{"type": "status", "message": "Connecting to Telegram..."}
{"type": "code_required", "message": "Confirmation code sent"}
{"type": "authorized", "message": "Authorization completed", "username": "akva_bot", ...}

Після закриття з'єднання сесія примусово завершується, тому повторні спроби починаються з нового start.

6. Сервіси діалогів

TDLibHelper (dialogs/services/tg_requests.py)

• Уніфікує виклики TDLib через tg_call() (повертає {ok, result, error}).
• Містить кешовані методи get_me(), get_chat(), get_user().
• get_chats(limit, offset_order, offset_chat_id, chat_list) підтримує пагінацію; chat_list опційно дозволяє отримати архів/папку; build_chat_item() повертає order (рядок) і positions.
• get_history(), get_message(), view_messages(), send_message(), forward_message(), reply_message(), get_contacts() охоплюють усі основні операції.
• Блок MEDIA завантажує файли через TDLib, передає їх у save_media(), повертає presigned URL або метадані.
• Методи для преміум-емодзі: get_full_info_premium_emoji(), get_premium_emoji_asset(), форматування тексту з кастомними емодзі (formated_msg(), utf16_index_to_py_index()).
• send_ws() — хелпер для пушу відповіді у Redis-канал chat_list_updates.

TDLibDialogService

• Фасад get_dialog() тягне історію, дані чату та парсить повідомлення.
• Позначає вхідні повідомлення прочитаними через helper.view_messages().
• Витягує дані відправника, ріплаїв, пересилань, обробляє photo/emoji/unsupported контент.
• Повертає вже відформатований payload для фронтенду.

save_to_cloud.py

• save_media() — завантаження локального файлу у MinIO/S3 через default_storage.
• generate_presigned_url() створює короткоживуче посилання на об'єкт.

utf_index_to_py_index.py

Конвертує UTF-16 індекси (які повертає TDLib) у Python-індекси, щоб коректно працювати з емодзі/сурогатами.

7. Лістенери та обробники

main_listener.py

• start_userbot_listener() відкриває TDLib-клієнт через SessionManager, реєструє updateNewMessage та запускає listen_for_commands().
• listen_for_commands() слухає Redis-канал tg_commands, приймає payload та виконує команди через TDLibHelper.
• Підтримувані команди: get_chats, search_user, get_user, open_dialog (опц. message_thread_id), send_message, forward_message, reply_message, edit_message, pin_message, unpin_message, download_file, archive_chat, unarchive_chat, delete_chat, leave_chat, chat_in_folder, pin_chat, import_contacts, get_prem_path.
• Результати надсилаються у chat_list_updates через send_ws(), щоб їх підхопив WebSocket-клієнт.

handle_new_update.py

• Прямий обробник updateNewMessage, що приходить із TDLib.
• Використовує TDLibDialogService.parse_message(), щоб отримати повний опис повідомлення (ID, текст, ентиті, reply/forward/медіа).
• Публікує результат у chat_list_updates разом із userbot_id та unread_count, тож push-події мають такий самий формат, як і історія open_dialog.

8. WebSocket API для діалогів

TDLibListChatsConsumer

• Після open_client підписується на chat_list_updates і може одночасно слухати кілька userbot-ів через userbot_ids (масив) або одиночний userbot_id.
• get_chats → відправляє команду у Redis з limit, offset_order, offset_chat_id, опц. chat_list (наприклад {"@type":"chatListArchive"} або рядок "chatListArchive").
• search_user, get_user, open_dialog, get_prem_path — тонкі проксі в Redis.
• open_dialog з message_thread_id відкриває історію конкретного топіка; без message_thread_id у форумних чатах повертає список топіків у форматі повідомлень (is_topic, message_thread_id, topic_name, topic_icon_emoji_id).
• send_message — базове відправлення тексту.
• forward_message — пересилає повідомлення між чатами без редагування контенту.
• delete_messages — видаляє повідомлення в чаті ("revoke": false -- > видаляє для себе, true -- > для всіх).
• reply_message — створює відповідь із посиланням на reply_to_message_id.
• edit_message — редагує текст повідомлення за message_id.
• pin_message / unpin_message — прикріплює або відкріплює повідомлення в чаті.
• download_file — завантажує файл за file_id (потрібен для якісніших фото).
• archive_chat / unarchive_chat — переносить чат в архів або повертає у головний список.
• delete_chat — видаляє історію та прибирає чат зі списку (опц. remove_from_chat_list, revoke).
• leave_chat — вихід з чату/каналу за chat_id.
• chat_in_folder — керує станом чату в папці (added/removed/pin/unpin).
• pin_chat — пін/анпін чату в заданому списку (опц. chat_list, дефолт — main).
• import_contacts — викликає TDLibHelper.get_contacts(), повертає результат у відповідному WS-івенті.
• Відсіює повідомлення за userbot_id, щоб користувач отримував лише свій стрім.
• Медіа приходять поступово через подію media_ready (файл/кастомні емодзі/іконка топіка), щоб UI міг оновлюватись без блокування основного потоку.

Події з Redis

• message — основний payload повідомлення або топіка (у форматі повідомлення).
• pinned_message — закріплені повідомлення з чату (якщо from_message_id==0 і message_thread_id==None).
• dialog_end — ознака завершення відвантаження історії.
• media_ready — поступове дозавантаження медіа: {kind: "file"|"custom_emoji", file_id|emoji_id, path|emoji_json|emoji_webm, chat_id, msg_id, message_thread_id}.
• dialog_error — помилка під час open_dialog.
• user_status — оновлення онлайна: {user_id, status, last_seen}.
• chat_action — typing/recording: {chat_id|user_id, message_thread_id, sender_id, action, progress}.
• chat_position — зміна ордеру/позицій: {chat_id, order|position|positions}.

Приклади payload-ів

{"action": "open_client", "userbot_ids": [1, 2], "user_id": 1}
{"action": "get_chats", "userbot_id": 1, "user_id": 1}
{"action": "get_chats", "userbot_id": 1, "chat_list": "chatListArchive"}
{"action": "open_dialog", "userbot_id": 1, "from_message_id": "0", "chat_id": "123"}
{"action": "open_dialog", "userbot_id": 1, "from_message_id": "0", "chat_id": "123", "message_thread_id": "456"}

// Відправити повідомлення
{"action": "send_message", "userbot_id": 1, "chat_id": "123", "text": "Привіт"}

// Переслати повідомлення
{"action": "forward_message", "userbot_id": 1, "to_chat_ids": ["488386685", "456456685"], "from_chat_id": "2123445553", "message_ids": ["984071798784", "1231231231"]}

// Видалити повідомлення в чаті
{"action": "delete_messages", "userbot_id": 1, "chat_id": "456456685", "message_ids": ["984071798784"], "revoke": false}

// Reply на конкретне повідомлення
{"action": "reply_message", "userbot_id": 1, "chat_id": "2123445553", "reply_to_message_id": "984121081856", "text": "Відповідаю"}

// Редагувати повідомлення
{"action": "edit_message", "userbot_id": 1, "chat_id": "2123445553", "message_id": "984121081856", "text": "Оновлений текст"}

// Прикріпити повідомлення + only_for_self: true (повідомлення буде прикріплене лише для вас)
{"action": "pin_message", "userbot_id": 1, "chat_id": "2123445553", "message_id": "984121081856"}

// Відкріпити повідомлення
{"action": "unpin_message", "userbot_id": 1, "chat_id": "2123445553", "message_id": "984121081856"}

// Завантажити файл за file_id (наприклад, високу якість фото)
{"action": "download_file", "userbot_id": 1, "file_id": 123456, "chat_id": "2123445553", "msg_id": "984121081856"}

// Архівувати чат
{"action": "archive_chat", "userbot_id": 1, "chat_id": "123"}

// Повернути чат з архіву
{"action": "unarchive_chat", "userbot_id": 1, "chat_id": "123"}

// Видалити чат (прибрати зі списку) revoke = true (видалити історію для всіх), якщо remove_from_chat_list false, то просто очистить історію, але залишить чат у списку
{"action": "delete_chat", "userbot_id": 1, "chat_id": "123", "remove_from_chat_list": true, "revoke": true}

// Вийти з каналу/чату
{"action": "leave_chat", "userbot_id": 1, "chat_id": "123"}

// Додати чат у папку (added дефолтно true)
{"action": "chat_in_folder", "userbot_id": 1, "chat_id": "123", "chat_folder_id": 35}

// Видалити чат з папки (added вказувати false, removed=true)
{"action": "chat_in_folder", "userbot_id": 1, "chat_id": "123", "chat_folder_id": 35, "removed": true}

// Пін чату в папці (added можна не вказувати)
{"action": "chat_in_folder", "userbot_id": 1, "chat_id": "123", "chat_folder_id": 35, "pin": true}

// Анпін чату в папці (added можна не вказувати)
{"action": "chat_in_folder", "userbot_id": 1, "chat_id": "123", "chat_folder_id": 35, "unpin": true}

// Пін/анпін чату в списку (дефолтно main)
{"action": "pin_chat", "userbot_id": 1, "chat_id": "123", "is_pinned": true}

9. Потік даних

Команди від фронтенду

1. React/SPA шле action у WebSocket (dialogs/ws).
2. WS-консюмер публікує JSON у Redis-канал tg_commands.
3. listen_for_commands() читає повідомлення, викликає TDLibHelper.
4. Результат (або помилка) повертається через send_ws() у канал chat_list_updates.
5. WS-консюмер відправляє payload назад клієнту.

Push-оновлення

1. TDLib кидає updateNewMessage.
2. handle_new_update парсить повідомлення через TDLibDialogService та формує payload із тими ж полями, що повертає open_dialog.
3. Подія з userbot_id, unread_count та деталями месиджу публікується у chat_list_updates й летить на фронт.
4. Якщо у повідомленні є файл/кастомне емодзі/іконка топіка, окремо приходить media_ready з метаданими (поступова доставка медіа).

10. Типові сценарії

11. Рекомендації з розширення

• Нові команди достатньо додати у listeners/main_listener.py (обробка) та у відповідний WS-консюмер.
• Тримайте SessionManager єдиною точкою входу: не створюйте Telegram напряму.
• GraphQL-шар може повторно використовувати ці сервіси; достатньо звертатись до нього як до внутрішнього API.