Документація 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) підтримує пагінацію; build_chat_item() повертає order як рядок.
• 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 (опц. topic_id), send_message, forward_message, reply_message, 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.
• search_user, get_user, open_dialog, get_prem_path — тонкі проксі в Redis.
• open_dialog з topic_id відкриває історію конкретного топіка; без topic_id у форумних чатах повертає список топіків у форматі повідомлень (is_topic, topic_id, topic_name, topic_icon_emoji_id).
• send_message — базове відправлення тексту.
• forward_message — пересилає повідомлення між чатами без редагування контенту.
• reply_message — створює відповідь із посиланням на reply_to_message_id.
• import_contacts — викликає TDLibHelper.get_contacts(), повертає результат у відповідному WS-івенті.
• Відсіює повідомлення за userbot_id, щоб користувач отримував лише свій стрім.
• Медіа приходять поступово через подію media_ready (файл/кастомні емодзі/іконка топіка), щоб UI міг оновлюватись без блокування основного потоку.

Події з Redis

• message — основний payload повідомлення або топіка (у форматі повідомлення).
• dialog_end — ознака завершення відвантаження історії.
• media_ready — поступове дозавантаження медіа: {kind: "file"|"custom_emoji", file_id|emoji_id, path|emoji_json|emoji_webm, chat_id, msg_id, topic_id}.
• dialog_error — помилка під час open_dialog.

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

{"action": "open_client", "userbot_ids": [1, 2], "user_id": 1}
{"action": "get_chats", "userbot_id": 1, "user_id": 1}
{"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", "topic_id": "456"}

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

// Переслати повідомлення
{"action": "forward_message", "userbot_id": 1, "to_chat_id": "488386685", "from_chat_id": "2123445553", "message_id": "984071798784"}

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

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.