tg_client WebSocket Docs: Auth

Endpoint

wss://<host>/ws/tg-auth/

Routing: tg_client/routing.py, consumer: tg_client/auth/consumers.py.

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

Клієнт підключається до /ws/tg-auth/, отримує {"type":"connected"}.
Надсилає start з userbot_id і phone.
Якщо Telegram вимагає код: приходить code_required, клієнт шле send_code.
Якщо Telegram замість коду вимагає підтвердження з іншого пристрою: приходить auth_method_choice_required, auth-сесія скидається, клієнт показує вибір і стартує новий start або start_qr.
Якщо потрібен 2FA: приходить password_required, клієнт шле send_password.
При успіху приходить authorized, профіль userbot оновлюється в БД.

Можливі проміжні стани: status, info, error.

Auth Commands

Action	Що приймає	Що повертає	Що робить
`start`	`userbot_id`, `phone`	`status`, далі `code_required` / `password_required` / `authorized` або `error`	Стартує TDLib auth session, запускає login flow.
`start_qr`	`userbot_id`, `phone`, опц. `other_user_ids`	`qr_required` / `authorized` або `error`	Стартує TDLib auth session і просить QR login link через `requestQrCodeAuthentication`.
`send_code`	`code`	`password_required` / `authorized` або `error`	Надсилає код підтвердження в активну auth-сесію.
`resend_code`	-	`code_required` з `auth_state_details` або `error`	Просить TDLib повторно надіслати код для активної auth-сесії.
`send_password`	`password`	`authorized` або `error`	Надсилає пароль 2FA в активну auth-сесію.

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

{
  "action": "start",
  "userbot_id": 1,
  "phone": "+380991112233"
}

{
  "action": "start_qr",
  "userbot_id": 1,
  "phone": "+380991112233"
}

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

{
  "action": "resend_code"
}

{
  "action": "send_password",
  "password": "my-2fa-password"
}

Response Types

type	Коли приходить	Payload
`connected`	Після відкриття WS-зʼєднання	`{"type":"connected","message":"WebSocket connected"}`
`status`	Проміжний технічний стан	Текст у `message` (наприклад, Connecting / Sending code)
`code_required`	Потрібен confirmation code	`{"type":"code_required","message":"Confirmation code sent"}`
`auth_method_choice_required`	`start` отримав від TDLib `authorizationStateWaitOtherDeviceConfirmation` замість коду	Auth-сесія вже скинута; фронт має показати вибір і запустити новий `start` або `start_qr`.
`password_required`	Потрібен 2FA пароль	`{"type":"password_required","message":"2FA password required"}`
`authorized`	Успішна авторизація	`type, message, username, tg_nickname, phone`
`info`	Інформаційна подія (наприклад, session already started)	`{"type":"info","message":"..."}`
`error`	Валідаційні/сесійні/TDLib помилки	`{"type":"error","message":"..."}`

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

{"type":"code_required","message":"Confirmation code sent","auth_state_details":{"state":"authorizationStateWaitCode","code_info":{"@type":"authenticationCodeInfo","phone_number":"+380991112233","type":{"@type":"authenticationCodeTypeSms","length":5},"next_type":{"@type":"authenticationCodeTypeSms","length":5},"timeout":60}}}

{"type":"auth_method_choice_required","message":"Telegram requires choosing an authorization method.","available_actions":["start","start_qr"],"session_reset":true,"auth_state_details":{"state":"authorizationStateWaitOtherDeviceConfirmation"}}

{"type":"qr_required","message":"Scan QR code in Telegram","link":"tg://login?token=...","auth_state_details":{"state":"authorizationStateWaitOtherDeviceConfirmation","link":"tg://login?token=..."}}

{"type":"password_required","message":"2FA password required"}

{"type":"authorized","message":"Authorization completed","username":"my_user","tg_nickname":"John Doe","phone":"+380991112233"}

{"type":"error","message":"Session not initialized"}

Важливі правила

start вимагає валідний phone з префіксом + і userbot_id.
start_qr повертає tg:// link; фронт має згенерувати QR-код із цього рядка.
auth_method_choice_required означає, що поточна TDLib-сесія закрита; для QR треба запускати новий start_qr.
send_code / resend_code / send_password працюють тільки після успішного start.
resend_code доступний тільки коли code_info.next_type присутній і code_info.timeout дорівнює 0; інакше backend поверне error без TDLib resend-запиту.
Після authorized auth-сесія очищається; для нового входу треба новий start.

Для REST auth див. accounts/docs/auth.