Démarrer

API du bot Telegram vs API Telegram : laquelle vous faut-il ?

API du Bot Telegram vs API Telegram

API du bot Telegram vs API Telegram : laquelle vous faut-il ?

Le Telegram Bot API et le API Telegram (également appelée l'API Utilisateur Telegram, construite sur MTProto) résolvent des problèmes différents. L'une gère un compte bot via HTTP. L'autre gère un vrai compte utilisateur via un protocole binaire que vous implémentez vous-même. Ce guide détaille où chacune d'elles vous bloque, point de terminaison par point de terminaison, et ce qu'il en coûte réellement de développer et de maintenir un client d'API Utilisateur Telegram par rapport à la connexion d'un compte existant via Unipile.
Construire avec Unipile
Voir la documentation

can-i-message-first.js
// API Bot : bloqué, l'utilisateur n'a jamais envoyé de message au bot const res = await bot.sendMessage(identifiantUtilisateur, "Bonjour"); // -> 403 Interdit : le bot a été bloqué par l'utilisateur ou n'a jamais commencé une conversation // API Utilisateur Telegram via Unipile : fonctionne, il s'agit d'un vrai compte // POST /v2/:account_id/chats/send const chat = await unipile.chats.create({ account_id : compteTelegramId, identifiants_utilisateur : [nom d'utilisateur], text: "Bonjour" });
chat.status: "envoyé"
Les deux modèles

API Bot Telegram vs API Utilisateur Telegram, dans un seul tableau

Si vous savez déjà que Telegram possède plusieurs API et que vous voulez simplement savoir laquelle s'applique à votre projet, ce tableau vous y mène en dix secondes. Si vous avez encore besoin d'avoir une vue d'ensemble des trois API de Telegram, lisez le guide de démarrage premièrement. Ici, nous allons un niveau plus loin sur les deux que les gens utilisent réellement : l'API Bot et l'API Utilisateur Telegram.
CritèresTelegram Bot APIAPI Utilisateur Telegram (MTProto)
Ce qu'il relieUn compte de bot, créé et possédé par votre applicationUn véritable compte d'utilisateur Telegram, lié à un numéro de téléphone
ProtocoleRequêtes et réponses HTTP standard, JSONMTProto, un protocole binaire personnalisé que vous implémentez
IndentificationsUn jeton de bot émis par @BotFatherid_api + clé d'API from my.telegram.org
Identité dans les discussionsAffiche un badge " bot " visible, distinct de celui d'une personneIndiscernible d'une personne utilisant l'application
Qui peut envoyer un message à quiLe bot ne peut répondre qu'une fois qu'un utilisateur a initié la conversationLe compte peut envoyer des messages à n'importe qui, comme n'importe quel utilisateur de Telegram
Mise en œuvre typeTout client HTTP, SDK officiels et communautairesTéléthon, Pyrogram, GramJS, TDLib ou un compte lié via Unipile
CoûtGratuit d'utilisationGratuit, coût de l'infrastructure auto-hébergée uniquement
Telegram Bot API
Se connecteUn compte de robot
ProtocoleHTTP, JSON
IndentificationsJeton du bot (BotFather)
IdentitéBadge de bot visible
À qui il peut envoyer des messagesSeuls les utilisateurs qui ont envoyé un message en premier
CoûtGratuit
API Utilisateur Telegram (MTProto)
Se connecteUn vrai compte d'utilisateur
ProtocoleMTProto, binaire
Indentificationsapi_id + api_hash
IdentitéIndiscernible d'une personne
À qui il peut envoyer des messagesN'importe qui, comme un utilisateur normal
CoûtGratuit, auto-hébergé, sans frais
Créez votre intégration Telegram
La question qui décide

À qui voulez-vous écrire en premier ?

Toutes les autres différences entre l'API Bot de Telegram et l'API Utilisateur de Telegram sont secondaires par rapport à celle-ci. Répondez-y d'abord et le reste de ce guide devient une liste de contrôle, et non une décision.
Un bot ne peut pas initier une conversation avec un utilisateur qui ne lui a jamais envoyé de message au préalable
Il s'agit d'une règle de la plateforme Telegram, et non d'une limitation d'Unipile ou d'un bug de bibliothèque. Un compte de bot ne peut répondre que dans une discussion que l'utilisateur a déjà ouverte, ou après qu'un utilisateur a appuyé sur un t.me lien profond ou rejoint un groupe dans lequel se trouve le bot. Si votre cas d'utilisation nécessite de contacter quelqu'un qui n'a pas encore interagi avec votre bot, l'API Bot n'est pas une option, quel que soit le framework ou la bibliothèque qui se trouve au-dessus.
L'API du bot fonctionne

L'utilisateur parle à votre bot en premier

Bots d'assistance, outils pilotés par des commandes, inscriptions aux notifications, chatbots liés depuis votre produit. L'utilisateur trouve votre bot, démarre la discussion, et à partir de là, tout se déroule comme un échange normal que l'API Bot gère bien.
API du bot bloquée

Vous devez faire le premier pas

Prospection commerciale, recrutement, messagerie client liée à une liste de contacts existante, ou tout flux de travail où votre produit initie le contact avec un utilisateur Telegram. Cela nécessite un véritable compte utilisateur, c'est-à-dire l'API utilisateur Telegram (MTProto), et non l'API Bot.
Matrice des capacités

Ce qui fonctionne réellement, point par point

Au-delà de la différence des gros titres, voici où chaque option vous bloque en pratique. " API Utilisateur Telegram (brute) " désigne un client MTProto construit par vos soins avec une bibliothèque telle que Telethon, Pyrogram, GramJS ou TDLib. " Unipile " désigne le même vrai compte utilisateur, connecté sans avoir à écrire de code MTProto vous-même.
CapacitéAPI de botAPI utilisateur Telegram (brute)Unipile
Engager la conversation avec un utilisateur qui n'a jamais envoyé de message en premierNonOui, sous réserve des paramètres de confidentialité de l'utilisateurOui, même règle que pour n'importe quel compte Telegram
Envoyer et recevoir des messages texteOui, dans les chats dont le bot fait partieOui,Oui,
Lire l'historique des messages d'avant l'arrivée du botNonOui,Oui,
Liste des participants au groupe, ajouter, supprimerLimité aux propres autorisations du botOui, si vous le construisezOui, getParticipantsList, addParticipant, removeParticipant
Administration du groupe : approuver, promouvoir, révoquerOui, seulement si le bot est un administrateurOui, si vous le construisezNon pris en charge
Canaux, communautés, diffusionsOui, si ajouté en tant qu'administrateurOui,Non pris en charge
Discussions secrètesSans objetOui, si vous le construisezNon pris en charge
Pièces jointes de contact, de lieu, de sondage et d'événementOui,Oui,Non pris en charge
Appels vocaux et vidéoNonPossible, effort de mise en œuvre élevéNon pris en charge
Thème de discussion, archivage, suppression de discussionSans objetOui, si vous le construisezNon pris en charge
Identité du compteSéparer l'identité du bot, badge visibleIdentité d'utilisateur réel, liée à un numéro de téléphoneVéritable identité d'utilisateur, votre compte existant
Gestion des sessions et des appareilsBasé sur des jetons, aucun concept d'appareilVous gérez vous-même la clé d'authentification MTProto et la double authentification (2FA)Géré via la propre fonctionnalité Appareils de Telegram
Démarrer une discussion à froid
API de botNon
API utilisateur (brut)Oui, dépendant de la confidentialité
UnipileOui,
Historique des messages avant de rejoindre
API de botNon
API utilisateur (brut)Oui,
UnipileOui,
Participants du groupe (obtenir / ajouter / supprimer)
API de botLimité aux autorisations du bot
API utilisateur (brut)Oui, construit par soi-même
UnipileOui, des points de terminaison dédiés
Administration de groupe
API de botOui, si le bot administrateur
API utilisateur (brut)Oui, construit par soi-même
UnipileNon pris en charge
Canaux, communautés, diffusions
API de botOui, en tant qu'administrateur
API utilisateur (brut)Oui,
UnipileNon pris en charge
Discussions secrètes
API de botSans objet
API utilisateur (brut)Oui, construit par soi-même
UnipileNon pris en charge
Pièces jointes de contact, de lieu, de sondage ou d'événement
API de botOui,
API utilisateur (brut)Oui,
UnipileNon pris en charge
Appels vocaux et vidéo
API de botNon
API utilisateur (brut)Possible, grand effort
UnipileNon pris en charge
Gestion des sessions / appareils
API de botBasé sur des jetons
API utilisateur (brut)Clé d'authentification autogérée + 2FA
UnipileFonctionnalité Appareils de Telegram
Ce que Unipile ne couvre pas sur Telegram
Canaux, communautés et diffusions, thème de discussion, discussions secrètes, contact, localisation, pièces jointes de sondage et d'événement, administration de groupe (approbation, promotion, révocations), suppression de discussion, archivage, et appels vocaux ou vidéo. Si votre projet a besoin de l'un d'entre eux, seul un client de l'API utilisateur Telegram fait maison couvre toute la surface.
Construisez-le avec Unipile
Le coût réel

Le coût réel de la construction sur MTProto

L'API Utilisateur Telegram est gratuite, mais " gratuit " ne couvre que la licence. Créer et maintenir soi-même un client d'API Utilisateur Telegram représente un véritable coût d'ingénierie qu'une intégration d'API Bot n'a jamais. Voici à quoi ressemble réellement ce coût.
01

Gestion des sessions et des clés d'authentification

MTProto est un protocole binaire, et non REST. Vous implémentez vous-même le schéma TL, l'échange de clés d'authentification et conservez la session résultante. Perdez la session et l'utilisateur doit se réauthentifier à partir de zéro.
02

Authentification à deux facteurs

Les comptes avec un mot de passe cloud nécessitent de gérer le processus d'authentification à deux facteurs (2FA) basé sur le protocole SRP de Telegram lors de la connexion. C'est une machine à états de plus à concevoir, tester et maintenir opérationnelle à chaque mise à jour du protocole Telegram.
03

Un api_id par numéro de téléphone

id_api et clé d'API sont émis le my.telegram.org sous "outils de développement d'API" et nécessitent un compte Telegram actif. Telegram permet un seul id_api par numéro de téléphone, ce qui façonne la manière dont vous obtenez vos identifiants de test et de production.
04

Comptes sous observation automatique

Les clients non officiels sont placés sous observation automatique par Telegram. Le flooding, le spam et le fait d'augmenter artificiellement les compteurs peuvent entraîner un bannissement permanent, ce qui signifie que la limitation du taux (rate limiting) et le préchauffage (warm-up) relèvent de votre responsabilité, et non d'une configuration par défaut de la bibliothèque.

shared-api-id-in-open-source.log
// Copier-coller un exemple d'api_id provenant d'un dépôt open source // au lieu d'enregistrer le vôtre sur my.telegram.org Erreur : API_ID_PUBLISHED_FLOOD // Telegram signale les valeurs api_id publiées dans le code public. Chaque application que vous livrez nécessite son propre api_id / api_hash, // un par numéro de téléphone, ou vos utilisateurs finaux rencontreront cette erreur.
Passez le travail de protocole
Rien de tout cela n'est nécessaire pour connecter un véritable compte Telegram
Unipile gère pour vous la session MTProto, le processus de connexion et le cycle de vie des identifiants. Vous obtenez un véritable compte Telegram humain connecté à votre produit sans avoir à coder un client à partir de zéro.
Commencez plutôt à construire
La troisième voie

Connecter un compte existant, ignorer la construction MTProto

La plupart des équipes ne veulent pas vraiment créer un client Telegram. Elles veulent les fonctionnalités d'un véritable compte utilisateur : engager des conversations, lire l'historique complet, gérer les participants aux groupes, sans avoir à développer une implémentation de protocole binaire. C'est ce que propose Unipile API Telegram est pour.
Se connecter via la fonctionnalité Appareils de Telegram
Unipile lie un compte d'utilisateur Telegram existant via la fonction Appareils de Telegram, le même mécanisme qui vous permet de vous connecter à Telegram Desktop ou Telegram Web. La connexion s'effectue par code QR ou via l'authentification hébergée avec fournisseurs : "TELEGRAM" pour un flux de connexion sans inscription préalable.
Pas d'api_id, pas d'api_hash, pas de MTProto à écrire
Vous ne gérez jamais vous-même l'échange de clés d'authentification, le schéma TL ou la double authentification (2FA). Le compte lié se comporte comme un véritable utilisateur Telegram parce qu'il en est un, et non un bot ou un client simulé.
Participants du groupe, via des points de terminaison dédiés
obtenirLaListeDesParticipants, ajouterUnParticipant, supprimerLeParticipant, exposé via POST, GET, ou encore SUPPRIMER /v2/{account_id}/chats/{chat_id}/participants. Aucun appel MTProto personnalisé à écrire pour la gestion des abonnements de base.
État de la session lié à la liste des appareils de Telegram
Si l'appareil Unipile est supprimé des sessions actives du compte dans Telegram, le statut du compte bascule vers déconnecté. Le cycle de vie de la session est visible et prévisible, et non une boîte noire que vous débuguez seul.
Créez votre fonctionnalité Telegram
Explorer l'API Telegram

connecter-compte-telegram.js
Connecter un compte utilisateur Telegram existant // via Hosted Auth, no MTProto code required const lien = await unipile.Authentification hébergée.create({ fournisseurs ["TELEGRAM"], expire le : "2026-12-31T23:59:59.000Z" }); // L'utilisateur scanne le code QR avec l'application Telegram // Le statut du compte devient "connecté" // GET /v2/{account_id}/chats/{chat_id}/participants const membres = await unipile.chats.obtenirLaListeDesParticipants(ID de discussion);
account.status: "connecté"
Mêmes règles, pas de raccourci pour les contourner
Un compte lié reste un compte Telegram et est soumis aux propres limites de Telegram : évitez les comptes flambant neufs pour un usage intensif, augmentez le volume progressivement et prévoyez au moins 10 à 20 secondes entre les messages. Voir le Guide de l'API Telegram et le guide d'envoi de message pour l'installation complète.
Arbre de décision

Lequel convient à votre cas

Trois questions, dans l'ordre. Arrêtez-vous à la première qui correspond à votre projet.
1
L'utilisateur m'envoie-t-il toujours des messages en premier, et le bot doit-il uniquement répondre aux commandes et aux messages ?
->Robots de support, notifications avec consentement préalable (opt-in), outils de commande où l'utilisateur initie le contact.API de bot
2
Avez-vous besoin de faire le premier pas, et avez-vous également besoin de canaux, de chats secrets, d'administration de groupe ou d'appels ?
->Couverture complète de la plateforme, et vous êtes disposé à créer et à maintenir votre propre client MTProto avec Telethon, Pyrogram, GramJS ou TDLib.API utilisateur Telegram, fait maison
3
Devriez-vous faire le premier pas, agir comme un vrai compte et avancer sans posséder MTProto ?
->Messagerie, historique des discussions et gestion des participants aux groupes sur un compte utilisateur connecté, avec la session gérée pour vous.Unipile
La plupart des équipes atterrissent ici
Connecter un vrai compte Telegram sans créer de client
Si votre projet doit initier le premier contact mais n'a pas besoin de canaux, de chats secrets ou d'appels, un compte lié via Unipile vous y amène sans avoir à maintenir une implémentation de l'API utilisateur Telegram.
Construisez-le avec Unipile

API Bot Telegram vs API Telegram - FAQ

Questions fréquentes sur le choix entre l'API Telegram Bot et l'API utilisateur Telegram (MTProto).
L'API Bot est une interface HTTP qui pilote un compte de bot et expose une surface délibérément limitée. L'API Telegram, également appelée API Client, utilise le protocole binaire MTProto et pilote un compte d'utilisateur réel avec l'ensemble complet des fonctionnalités. Ce sont des types de compte différents, et non deux versions d'une même chose.
Demandez à qui vous devez écrire. Si vos utilisateurs vous envoient un message en premier et qu'une identité de bot est acceptable, utilisez l'API Bot. Si vous devez contacter des personnes qui ne vous ont pas contacté, ou agir en tant que personne réelle, vous avez besoin d'un accès par compte utilisateur.
Non. L'utilisateur doit initier la conversation en premier. C'est la seule limite qui détourne la plupart des produits de l'API Bot, et aucun point de terminaison ne permet de la contourner.
Non. L'API Bot a seulement besoin du jeton de bot que vous donne BotFather. api_id et api_hash proviennent de my.telegram.org et sont destinés à l'API Client, avec un seul api_id autorisé par numéro de téléphone.
Assez difficile pour que presque personne ne l'écrive de zéro. Vous gérez la persistance de session, l'authentification à deux facteurs, la reconnexion et un protocole binaire. La plupart des équipes utilisent Telethon, Pyrogram, GramJS ou TDLib, et gèrent tout de même le cycle de vie de la session.
C'est un autre nom pour l'API client, l'interface MTProto qui s'authentifie en tant qu'utilisateur Telegram réel plutôt qu'en tant que bot.
Oui. La connexion d'un compte existant via la fonctionnalité Appareils de Telegram donne accès au compte utilisateur sans implémenter MTProto. C'est ainsi que Unipile lie les comptes Telegram, via une connexion par code QR ou un flux d'authentification hébergé.
Vous avez encore des questions ? Notre équipe est là pour vous aider.
Parler à un expert
fr_FRFR
en_USEN es_ESES de_DEDE it_ITIT pt_BRBR nl_NLNL pl_PLPL tr_TRTR fr_FRFR