Formats des comptes et des sessions

TgWitness se connecte en tant que compte utilisateur Telegram (et non en tant que bot) via MTProto, à l’aide de Telethon. Chaque compte dispose de son propre espace de travail (appelé « workspace » dans l’ API et les outils en ligne de commande) avec sa propre session, ses propres sources, son propre journal et sa propre clé de signature.

Les fichiers de session, les chaînes de session et les clés d’authentification constituent des autorisations de compte : toute personne qui en détient une peut agir au nom de ce compte. Ils ne contiennent pas l’historique des messages.

[!AVERTISSEMENT] N’utilisez rien que vous ne puissiez vous permettre de perdre. Nous vous déconseillons vivement de connecter des comptes personnels ou de toute autre nature présentant une valeur particulière, ainsi que de créer un identifiant API / un hachage API sur un compte auquel vous tenez. Il ne s’agit pas ici d’un manque de tests de TgWitness : Telegram restreint et suspend définitivement des comptes de manière imprévisible — pour des volumes de requêtes qu’il juge excessifs, quel que soit le client ou l’objectif, sans documentation adéquate. De nombreuses suspensions sont irréversibles. Utilisez des comptes dédiés. Le bon déroulement des tests dépend de Telegram, et non du logiciel, et ne garantit rien pour la suite.

• En bref
• Avant de commencer : identifiant API et hachage API
• Numéro de téléphone · Code QR · Clé d'authentification + identifiant DC
• Fichiers de compte: Telethon .session · Pyrogram .session · Paire session + JSON · TData · StringSession · Fichier JSON du compte
• Identifiez ce dont vous disposez · Formats non pris en charge
• Comptes multiples · Assurer la sécurité des fichiers de compte · Dépannage

En bref#

TgWitness identifie les fichiers en fonction de leur contenu, et non de leur nom. Le fait de renommer un fichier ne le convertit jamais.

Avant de commencer : identifiant API et hachage API#

Vous pouvez vous connecter sans créer d’application API Telegram. Lorsqu’aucune paire n’est saisie, importée ou déjà enregistrée dans l’espace de travail, TgWitness sélectionne une paire au hasard parmi son pool intégré de 50 paires API publiques (tgwitness/api_pool.py). Si Telegram refuse une paire (API_ID_INVALID, API_ID_PUBLISHED_FLOOD, UPDATE_APP_TO_LOGIN), la suivante est essayée, jusqu’à huit par connexion ; les paires refusées sont ignorées jusqu’au redémarrage. La paire utilisée pour la connexion est enregistrée avec le compte et réutilisée pour celui-ci. Un identifiant API et un hachage API identifient l’application auprès de Telegram ; ils n’autorisent pas un compte à eux seuls.

Pour utiliser votre propre application à la place (c’est le compte qui l’enregistre qui est exposé à un risque ; voir « Pourquoi un pool d’API intégré ? ») :

1. Ouvrez my.telegram.org et connectez-vous avec n'importe quel numéro de téléphone dont vous disposez. Le code vous est envoyé dans l'application Telegram, et non par SMS.
2. Choisissez des outils de développement d'API.
3. Créer une application : titre et nom court au choix (5 à 32 lettres), plateforme « Desktop ». Les champs « URL » et « Description » peuvent rester vides.
4. Copiez l’api_id de l’application (un nombre) et l’api_hash de l’application (32 caractères hexadécimaux).

Dans le panneau, les champs « API ID » et « Hash » se trouvent sous le formulaire de connexion. Vous pouvez coller une seule paire api_id:api_hash dans le champ « API ID » : les deux champs seront alors automatiquement remplis. Une seule paire peut être utilisée pour tous vos comptes. Une fois la connexion établie, ces informations sont enregistrées, chiffrées, dans cet espace de travail uniquement et ne sont jamais renvoyées au navigateur.

Trois types d’informations d’identification sont concernés :

Si l’accès à Telegram doit se faire via un proxy, configurez-le d’abord dans Compte → Paramètres → Paramètres de connexion → Modifier l’itinéraire de connexion.

Numéro de téléphone#

1. Ouvrez un compte, sélectionnez l'onglet « Téléphone », puis saisissez le numéro au format international, par exemple +44 7700 900123. Les espaces et les tirets sont supprimés automatiquement.
2. Cliquez sur « Continuer ». Les champs « API ID » et « Hash » peuvent rester vides.
3. Saisissez le code envoyé par Telegram (généralement dans l'application Telegram ; la réception par SMS n'est pas garantie).
4. Si le compte dispose d’une authentification en deux étapes, saisissez ce mot de passe. Il ne s’agit ni du jeton du panneau ni du code d’accès de l’appareil.
5. Vérifiez l'identifiant du compte affiché après la connexion, puis sélectionnez les sources.

Les identifiants de connexion et le mot de passe 2FA ne sont jamais enregistrés sur le disque.

Code QR#

Utilisez cette fonction lorsque le compte est déjà connecté sur un téléphone ou un autre ordinateur.

1. Onglet « Code QR » → Afficher le code QR. Les champs « ID API » et « Hachage » peuvent rester vides.
2. Sur l’appareil connecté : Paramètres → Appareils → Associer un appareil de bureau, scannez le code puis confirmez.
3. Saisissez le mot de passe 2FA dans TgWitness si Telegram vous le demande.

L'image QR est générée localement. Les codes ont une durée de validité limitée ; cliquez sur « Générer un autre code QR » pour réessayer. Le verrouillage du panneau, le changement d'espace de travail ou le lancement d'une nouvelle session annulent un code en attente.

Clé d'authentification + identifiant DC#

Une clé d'autorisation (Auth Key) est la clé d'autorisation brute de 256 octets qui sous-tend chaque session Telegram, représentée sous la forme de 512 caractères hexadécimaux, accompagnée du numéro du centre de données DC 1 à 5.

1. Onglet « Clé d'authentification ». Collez la clé complète ; une clé raccourcie contenant « … » ne fonctionnera pas.
2. Sélectionnez l'identifiant DC fourni avec la clé.
3. Vous pouvez, si vous le souhaitez, saisir l’identifiant utilisateur. TgWitness refuse alors la connexion si Telegram signale un compte différent.
4. Compte Press Connect.

Une clé d'authentification (512 caractères) n'est pas un hachage API (32 caractères). La même clé peut également être importée au format JSON ; voir « Account JSON ».

Fichiers de compte#

Ouvrez « Ajouter un compte » → « Fichiers » et sélectionnez jusqu’à quatre fichiers appartenant à un même compte, pour un total de 8 Mio, puis cliquez sur « Connecter le compte ».

• Les fichiers sont convertis en mémoire sur votre serveur TgWitness. Les fichiers téléchargés ne sont pas stockés, les fichiers ZIP ne sont pas extraits sur le disque et aucun service externe n’est sollicité.
• La session ainsi obtenue est ensuite vérifiée auprès de Telegram. Si un fichier mentionne un identifiant d’utilisateur, celui-ci doit correspondre au compte indiqué par Telegram.
• Les fichiers décrivant différents comptes ou différents identifiants API sont rejetés au lieu d’en choisir un seul.
• Le champ « Code d'accès ou texte de session » contient le champ « TData local passcode », une zone permettant de coller une StringSession et de lire des fichiers sans se connecter (remplit le formulaire sans contacter Telegram).

Téléthon .session#

Fermez d’abord le programme qui a créé le fichier. Si my_account.session-journal ou my_account.session-wal se trouve à côté, la base de données n’est pas finalisée : ouvrez puis fermez correctement le client d’origine. La suppression de ces fichiers « sidecar » peut laisser une copie corrompue.

Pyrogram .session#

L'identifiant utilisateur enregistré est vérifié auprès de Telegram lors de la connexion.

Paire session + JSON#

Les comptes sont souvent distribués sous la forme de deux fichiers portant le même nom, par exemple 447700900123.session et 447700900123.json. Sélectionnez-les tous les deux en même temps.

• À partir du fichier JSON, TgWitness utilise app_id/api_id et app_hash/api_hash ; vous n’avez donc généralement pas besoin de saisir d’identifiants d’API.
• Les autres champs tels que phone, device, sdk, app_version, lang_pack ou un mot de passe twoFA enregistré sont ignorés. Si le compte dispose d’une authentification à deux facteurs (2FA), TgWitness vous la demande.
• Un fichier JSON en soi ne contient que des métadonnées. En l’absence de fichier de session, veuillez poursuivre la connexion via votre téléphone ou à l’aide d’un code QR.

Telegram Desktop (TData)#

TData correspond au dossier « tdata » de l’application Telegram Desktop (l’application multiplateforme disponible sur desktop.telegram.org).

Pour l'importer :

Avertissement concernant les sessions parallèles. L’importation de TData réutilise la clé d’autorisation de Telegram Desktop ; elle ne crée pas de connexion indépendante. N’utilisez pas cette clé simultanément dans Desktop et TgWitness. Telegram peut invalider l’autorisation avec AUTH_KEY_DUPLICATED, rendant les deux instances inutilisables jusqu’à une nouvelle connexion.

Fermez complètement Desktop, y compris son processus dans la barre d’état, et veillez à ce que cette instance reste fermée pendant que TgWitness utilise la session importée. Quittez l’application, ne vous déconnectez pas et ne révoquez pas la session : la révocation invalide également la copie importée. Si vous avez besoin que les deux clients fonctionnent simultanément, connectez-vous à TgWitness via votre téléphone ou un code QR pour créer votre propre autorisation. Il est recommandé d’utiliser un compte dédié, mais cela ne garantit pas pour autant la sécurité de l’utilisation parallèle de clés clonées.

Cela s'applique également aux fichiers .session importés, au texte StringSession et à la clé d'authentification au format HEX. Les autres clients disposant de leurs propres autorisations créées de manière indépendante peuvent rester connectés. Consultez la documentation de Telegram relative à AUTH_KEY_DUPLICATED.

1. Quittez complètement Telegram Desktop.

2. Créez un fichier ZIP ne contenant que ces deux éléments provenant de tdata :

   • key_datas
   • le fichier de 16 caractères se terminant par « s » situé à côté, généralement « D877F783D5D3EF8Cs »

   La compression de l’intégralité du dossier avec son cache multimédia dépasse généralement les limites (512 entrées, 32 Mio décompressés). 3. Sélectionnez le fichier ZIP dans « Fichiers ». Si Telegram Desktop dispose d’un code d’accès local, saisissez-le d’abord dans le champ « Code d’accès » ou « Texte de session ». Il ne s’agit pas du mot de passe 2FA.

Prise en charge : un compte par archive, stockage moderne key_datas/key_data0/key_data1, code d'accès local. Non pris en charge : les dossiers contenant plusieurs comptes connectés, les anciennes versions de la version de bureau, les fichiers ZIP protégés par mot de passe et l'application native distincte pour macOS « Telegram for macOS ».

Telethon StringSession#

Une seule ligne de texte, commençant généralement par « 1 » et comptant environ 350 caractères. Importez-la sous forme de fichier « .txt » ou « .tgwitness-session » (4 Ko maximum), ou collez-la dans le champ « Code d'accès » ou « Texte de session ». Seules les chaînes Telethon sont acceptées ; les chaînes Pyrogram et TDLib utilisent des formats différents.

Fichier JSON du compte#

Un objet JSON, d'une taille maximale de 64 KiB, dans un fichier se terminant par .json.

Si un pseudonyme et le nom principal sont tous deux présents, ils doivent correspondre. Exemples :

{ "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
}

Le premier exemple ne concerne que la saisie des identifiants API ; connectez-vous par téléphone ou via un code QR, ou ajoutez un fichier de session. Les listes groupées (un tableau JSON de comptes) ne sont pas acceptées.

Identifiez ce dont vous disposez#

Formats non pris en charge#

Comptes multiples#

Appuyez sur + à côté du sélecteur de compte, ou ouvrez Compte → Paramètres → Paramètres de connexion → Espaces de travail, saisissez un libellé et connectez-vous.

• N’importe quel nombre d’espaces de travail, y compris l’espace principal. Chacun dispose de sa propre session, de son itinéraire de proxy, de ses sources, de sa politique de capture, de son journal, de sa clé de signature, de ses points de contrôle et de ses exportations.
• Le fait de changer d'espace de travail affiché ne met pas les autres en pause.
• Un journal reste lié au compte qui l’a créé. Se connecter avec un autre compte nécessite un autre espace de travail, et un même compte ne peut pas être attribué à deux espaces de travail.
• Le jeton du panneau principal contrôle l’ensemble des espaces de travail. Les droits d’accès accordés permettent de limiter l’accès d’autres personnes à certains comptes et discussions, avec des autorisations distinctes et des limites de session.
• La fonction « Comptes » permet de renommer un espace de travail et d’en supprimer un ajouté, avec sa session, son journal, ses sources et sa clé de signature. L’espace de travail principal ne peut pas être supprimé depuis le panneau.

Importation par lots et groupes de comptes#

Ouvrez Comptes → Importer des comptes pour ajouter plusieurs comptes, associer les fichiers par nom et voir le résultat de chaque connexion. Chaque compte dispose de son propre espace de travail. Les groupes peuvent copier certains réglages depuis un modèle sans fusionner les sessions, les clés ni les preuves. Consultez le guide d’importation et des groupes et le tableau de bord du pool MTProxy.

Se déconnecter#

Compte → Se déconnecter de Telegram (avec la surveillance en pause) demande à Telegram de mettre fin à la session ; celle-ci disparaît donc également de la rubrique Paramètres → Appareils du compte, et la session est supprimée du coffre-fort de l’espace de travail. Le journal, les sources, les paramètres et la clé de signature sont conservés, et le journal enregistre la déconnexion. L’espace de travail appartient toujours à son compte : seul ce compte peut s’y reconnecter. Si Telegram ne répond pas, la session est tout de même supprimée ici et le panneau l’indique ; mettez-y fin dans Telegram sous Paramètres → Appareils.

Convertir une session Telethon hors ligne#

Le panneau importe directement les fichiers .session. Pour une conversion hors ligne vers un fichier StringSession, exécutez depuis le dossier du projet :

.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

Le convertisseur lit uniquement les fichiers SQLite de Telethon (jusqu’à 64 Mio), ne modifie jamais les données d’entrée, n’effectue aucune requête réseau et refuse de remplacer un fichier de sortie existant.

Assurer la sécurité des fichiers de compte#

• Traitez chaque .session, fichier ZIP TData, StringSession, clé d’authentification et fichier JSON de compte comme un mot de passe. TgWitness conserve les informations d’autorisation importées dans son coffre-fort chiffré ; vous pouvez supprimer les fichiers d’origine par la suite.
• N’exécutez pas la même autorisation dans deux programmes à la fois. Telegram pourrait la révoquer (AUTH_KEY_DUPLICATED), et les deux instances cesseraient alors de fonctionner.
• Une session expirée ou révoquée ne peut pas être réactivée par conversion. Veuillez vous reconnecter.

Dépannage#

Voir également : connexion et sécurité pour les proxys et le chiffrement, ainsi que le fonctionnement de la collecte des données enregistrées après connexion.