Аккаунты и форматы сессий

TgWitness входит в систему как учетная запись пользователя Telegram (а не как бот) через протокол MTProto с использованием Telethon. Каждая учетная запись находится в собственном рабочем пространстве (называемом «workspace» в API и инструментах командной строки) с собственной сессией, источниками, журналом и ключом подписи.

Файлы сеансов, строки сеансов и ключи аутентификации являются средствами авторизации учетной записи: любой, кто имеет один из них, может действовать от имени этой учетной записи. Они не содержат истории сообщений.

[!ПРЕДУПРЕЖДЕНИЕ] Не используйте то, что вы не можете себе позволить потерять. Мы настоятельно не рекомендуем подключать личные или иные ценные учетные записи, а также создавать API-идентификатор / API-хэш на учетной записи, которая для вас важна. Дело не в том, что TgWitness не прошел тестирование: Telegram неожиданно ограничивает доступ и навсегда блокирует аккаунты — при объёме запросов, который он считает чрезмерным, независимо от клиента или цели, без надлежащей документации. Многие блокировки неподдаются отмене. Используйте специальные аккаунты. Бесперебойное проведение тестов зависит от Telegram, а не от программного обеспечения, и не гарантирует ничего на будущее.

• Краткий обзор
• Прежде чем начать: идентификатор API и хеш API
• Номер телефона · QR-код · Ключ аутентификации + идентификатор DC
• Файлы учетных записей: Telethon .session · Pyrogram .session · Пара «сессия + JSON» · TData · StringSession · JSON-файл учетной записи
• Определите, чем вы располагаете · Неподдерживаемые форматы
• Наличие нескольких учётных записей · Обеспечение безопасности файлов учетных записей · Устранение неполадок

Краткий обзор#

TgWitness распознает файлы по их содержимому, а не по именам. Переименование файла никогда не приводит к его преобразованию.

Прежде чем начать: идентификатор API и хеш API#

Вы можете войти в систему без создания приложения Telegram API. Если пара не введена, не импортирована или уже не сохранена в рабочей области, TgWitness выбирает пару из встроенного пула, состоящего из 50 общедоступных пар API (tgwitness/api_pool.py), в случайном порядке. Если Telegram отклоняет пару (API_ID_INVALID, API_ID_PUBLISHED_FLOOD, UPDATE_APP_TO_LOGIN), пробуется следующая, до восьми раз за один вход в систему; отклоненные пары пропускаются до перезапуска. Пара, с помощью которой был осуществлен вход, сохраняется вместе с учётной записью и повторно используется для неё. Идентификатор API и хэш API идентифицируют приложение в Telegram; они сами по себе не авторизуют учётную запись.

Если вы предпочитаете использовать собственное приложение (в этом случае риску подвергается учетная запись, на которой оно зарегистрировано; см. раздел «Зачем нужен встроенный пул API?»):

1. Откройте сайт my.telegram.org и войдите, указав любой номер телефона, который принадлежит вам. Код приходит в приложение Telegram, а не в виде SMS.
2. Выберите инструменты для разработки API.
3. Создайте приложение: укажите любое название и краткое имя (5–32 буквы), платформа — «Настольный компьютер». Поля «URL» и «Описание» можно оставить пустыми.
4. Скопируйте App api_id (число) и App api_hash (32 шестнадцатеричных символа).

В панели под формой входа указаны поля «Идентификатор API» и «Хеш». Вы можете ввести одну пару api_id:api_hash в поле «Идентификатор API», и оба поля будут заполнены. Одну пару можно использовать для всех ваших учётных записей. После успешного входа данные сохраняются в зашифрованном виде исключительно в данной рабочей среде и никогда не отправляются обратно в браузер.

Здесь задействованы три различных типа учетных данных:

Если для доступа к Telegram требуется прокси-сервер, сначала настройте его в разделе «Аккаунт» → «Настройки» → «Настройки подключения» → «Изменить маршрут подключения».

Номер телефона#

1. Откройте раздел «Аккаунт», перейдите на вкладку «Телефон» и введите номер в международном формате, например, +44 7700 900123. Пробелы и дефисы удаляются автоматически.
2. Нажмите «Продолжить». Поля «API ID» и «Хеш» можно оставить пустыми.
3. Введите код, отправленный Telegram (обычно в приложение Telegram; доставка по SMS не гарантируется).
4. Если для аккаунта настроена двухэтапная аутентификация, введите соответствующий пароль. Это не токен панели и не код доступа к устройству.
5. Проверьте идентификатор учетной записи, отображаемый после входа в систему, а затем выберите источники.

Коды входа и пароль двухфакторной аутентификации (2FA) никогда не записываются на диск.

QR-код#

Используйте эту функцию, если учетная запись уже авторизована на телефоне или другом компьютере.

1. Вкладка «QR-код» → Показать QR-код. Поля «API ID» и «Хеш» можно оставить пустыми.
2. На устройстве, на котором выполнен вход: «Настройки» → «Устройства» → «Привязать настольное устройство», отсканируйте код и подтвердите.
3. Введите пароль двухфакторной аутентификации (2FA) в TgWitness, если Telegram запрашивает его.

Изображение QR-кода генерируется локально. Срок действия кодов истекает; нажмите «Сгенерировать другой QR-код», чтобы повторить попытку. Блокировка панели, переключение рабочего пространства или вход под другим аккаунтом приводят к аннулированию кода, ожидающего обработки.

Ключ аутентификации + идентификатор DC#

Ключ авторизации — это исходный 256-байтовый ключ авторизации, лежащий в основе каждого сеанса Telegram, записанный в виде 512 шестнадцатеричных символов вместе с номером центра обработки данных DC 1–5.

1. Вкладка «Ключ аутентификации». Вставьте полный ключ; сокращённый ключ, содержащий символ …, не будет работать.
2. Выберите идентификатор DC, предоставленный вместе с ключом.
3. По желанию введите идентификатор пользователя. В этом случае TgWitness откажется подключаться, если Telegram сообщит о другом аккаунте.
4. Аккаунт в Press Connect.

Ключ авторизации (512 символов) не является хешем API (32 символа). Тот же ключ также можно импортировать в формате JSON; см. раздел «JSON-файл учетной записи».

Файлы учетных записей#

Откройте «Добавить аккаунт» → «Файлы» и выберите до четырёх файлов, относящихся к одному аккаунту, общим объёмом 8 MiB, затем нажмите «Подключить аккаунт».

• Файлы конвертируются в памяти на вашем сервере TgWitness. Загруженные файлы не сохраняются, архивы ZIP не распаковываются на диск, и не происходит обращения к каким-либо внешним сервисам.
• Полученный файл затем сверяется с данными Telegram. Если в файле указан идентификатор пользователя, он должен совпадать с идентификатором учетной записи, указанным в отчёте Telegram.
• Файлы, в которых описываются разные учётные записи или разные учетные данные API, отклоняются, вместо того чтобы выбрать одну из них.
• Поле «Пароль или текст сеанса» содержит поле локального пароля TData — поле для вставки StringSession и чтения файлов без входа в систему (заполняет форму без обращения к Telegram).

Телемарафон .session#

Сначала закройте программу, создавшую файл. Если рядом с ним присутствует файл my_account.session-journal или my_account.session-wal, это означает, что база данных не завершена: откройте и корректно закройте исходный клиент. Удаление этих вспомогательных файлов может привести к появлению повреждённой копии.

Pyrogram .session#

При входе в систему сохраненный идентификатор пользователя сверяется с данными Telegram.

Пара «сессия + JSON»#

Отчёты часто предоставляются в виде двух файлов с одинаковыми именами, например, 447700900123.session и 447700900123.json. Выберите оба файла одновременно.

• На основании данных JSON TgWitness использует app_id/api_id и app_hash/api_hash, поэтому вам как правило, не требуется вводить учетные данные API.
• Другие поля, такие как phone, device, sdk, app_version, lang_pack или сохраненный пароль twoFA, игнорируются. Если для учетной записи настроена двухфакторная аутентификация (2FA), TgWitness запрашивает её.
• Сам по себе файл JSON представляет собой лишь метаданные. При отсутствии файла сеанса продолжайте с помощью входа через телефон или QR-код.

Telegram Desktop (TData)#

TData — это папка tdata приложения Telegram Desktop (кроссплатформенного приложения с сайта desktop.telegram.org).

Чтобы импортировать его:

Предупреждение о параллельных сессиях. При импорте TData повторно используется ключ авторизации Telegram Desktop; он не создаёт независимый логин. Не используйте этот ключ одновременно в Desktop и TgWitness. Telegram может аннулировать авторизацию с помощью AUTH_KEY_DUPLICATED, в результате чего обе копии станут непригодными для использования до момента нового входа в систему.

Полностью закройте Desktop, включая его процесс в системном трее, и не открывайте эту копию, пока TgWitness использует импортированную сессию. Закройте программу, не выходите из системы и не отзывайте сессию: отзыв также приводит к недействительности импортированной копии. Если вам необходимо, чтобы оба клиента работали одновременно, войдите в TgWitness с помощью телефона или QR-кода, чтобы создать собственную авторизацию. Рекомендуется использовать отдельную учётную запись, однако это не гарантирует безопасность параллельного использования клонированных ключей.

Это также относится к импортированным .session файлы, текст StringSession и шестнадцатеричный код авторизационного ключа. Другие клиенты с собственными, независимо созданными авторизациями могут оставаться авторизованными. См. документацию Telegram по AUTH_KEY_DUPLICATED.

1. Полностью закройте Telegram Desktop.

2. Создайте ZIP-архив, содержащий только эти два элемента из tdata:

   • key_datas
   • 16-символьный файл с расширением «s», расположенный рядом с ним, обычно «D877F783D5D3EF8Cs»

   Сжатие всей папки вместе с кэшем мультимедиа, как правило, превышает установленные ограничения (512 записей, 32 MiB в распакованном виде). 3. Выберите ZIP-файл в разделе «Файлы». Если у Telegram Desktop установлен локальный пароль, сначала введите его в поле «Пароль» или «Текст сеанса». Это не пароль двухфакторной аутентификации (2FA).

Поддерживается: один аккаунт на архив, современное хранилище key_datas/key_data0/key_data1, локальный пароль. Не поддерживается: папки с несколькими авторизованными аккаунтами, устаревшие версии десктопного приложения, ZIP-архивы, защищённые паролем, а также отдельное нативное приложение для macOS «Telegram для macOS».

Telethon StringSession#

Одна строка текста, обычно начинающаяся с 1 и содержащая около 350 символов. Загрузите её в виде файла .txt или .tgwitness-session (размером не более 4 КиБ) или вставьте в поле «Пароль» или «Текст сеанса». Принимаются только строки формата Telethon; строки Pyrogram и TDLib используют другие форматы.

JSON-файл учетной записи#

Один объект JSON размером не более 64 КиБ в файле с расширением .json.

Если указаны как псевдоним, так и настоящее имя, они должны совпадать. Примеры:

{ "app_id": 1234567, "app_hash": "0123456789abcdef0123456789abcdef" }

{
  "api_id": 1234567,
  "api_hash": "0123456789abcdef0123456789abcdef",
  "auth_key": "REPLACE_WITH_ALL_512_HEXADECIMAL_CHARACTERS",
  "dc_id": 2,
  "user_id": 123456789
}

В первом примере заполняются только учетные данные API; войдите в систему с помощью телефона или QR-кода либо добавьте файл сеанса. Массовые списки (массив JSON с учетными записями) не принимаются.

Определите, чем вы располагаете#

Неподдерживаемые форматы#

Наличие нескольких учётных записей#

Нажмите кнопку «+» рядом с выбором учетной записи или откройте «Учетная запись» → «Настройки» → «Настройки подключения» → «Рабочие пространства», введите название и войдите в систему.

• Неограниченное количество рабочих пространств, включая основное. Каждое из них имеет собственную сессию, прокси- маршрут, источники, политику сбора данных, журнал, ключ подписи, контрольные точки и настройки экспорта.
• Переключение между отображаемыми рабочими пространствами не приводит к приостановке работы остальных.
• Журнал привязан к учетной записи, с которой он был создан. Для входа под другой учетной записью требуется отдельное рабочее пространство, при этом одна учетная запись не может быть привязана к двум рабочим пространствам.
• Токен главной панели управляет всеми рабочими пространствами. Предоставленный доступ позволяет ограничить доступ других пользователей к выбранным аккаунтам и чатам с помощью отдельных прав доступа и ограничений по продолжительности сеанса.
• Функция «Учётные записи» позволяет переименовать рабочую область и удалить добавленную рабочую область вместе с её сессией, журналом, источниками и ключом подписи. Главную рабочую область нельзя удалить с панели.

Массовый импорт и группы аккаунтов#

Откройте Аккаунты → Импорт учетных записей, чтобы добавить несколько аккаунтов, объединить файлы по имени и увидеть результат каждого входа. Для каждого аккаунта создаётся отдельное рабочее пространство. Группы позволяют копировать выбранные настройки из образца без объединения сессий, ключей и доказательств. См. руководство по импорту и группам и панель пула MTProxy.

Выйти#

«Учётная запись» → «Выйти из Telegram» (с приостановкой наблюдения) отправляет запрос в Telegram на завершение сеанса, в результате чего он также исчезает из раздела «Настройки» → «Устройства» данной учётной записи и удаляется из хранилища рабочего пространства. Журнал, источники, настройки и ключ подписи сохраняются, и в журнале фиксируется факт выхода из системы. Рабочая область по-прежнему принадлежит данной учетной записи: только эта учетная запись может подключиться к ней повторно. Если Telegram не отвечает, сессия всё равно удаляется здесь, и на панели отображается соответствующее сообщение; завершите её в Telegram в разделе «Настройки» → «Устройства».

Конвертировать сессию Telethon в автономном режиме#

Панель напрямую импортирует файлы формата .session. Для автономного преобразования в файл StringSession выполните из папки проекта следующую команду:

.venv\Scripts\python.exe -m tgwitness.sessions account.session --out account.tgwitness-session   # Windows

.venv/bin/python -m tgwitness.sessions account.session --out account.tgwitness-session          # Linux/macOS

Конвертер поддерживает только формат Telethon SQLite (объёмом до 64 MiB), никогда не изменяет исходные данные, не отправляет сетевых запросов и не перезаписывает существующий выходной файл.

Обеспечение безопасности файлов учетных записей#

• Относитесь к каждому .session, TData ZIP, StringSession, Auth Key и JSON-файлу учетной записи как к паролю. TgWitness хранит импортированные данные авторизации в зашифрованном хранилище; вы можете удалить исходные файлы впоследствии.
• Не запускайте одну и ту же авторизацию одновременно в двух программах. Telegram может отозвать её (AUTH_KEY_DUPLICATED), и обе копии перестанут работать.
• Сеанс, срок действия которого истек или который был отозван, не может быть восстановлен посредством преобразования. Войдите в систему заново.

Устранение неполадок#

См. также: подключение и безопасность прокси-серверов и шифрования, а также принципы сбора данных, которые фиксируются после входа в систему.