API Telegram avec Python : Bot API, MTProto et comptes liés

Guide d'implémentation Python

Le API Telegram Python guide : du code fonctionnel pour chaque approche

Une visite guidée orientée code du API de bot Telegram pour Python: le sendMessage appel avec demandes, un bot minimal avec python-telegram-bot, un vrai compte lié avec Telethon, Pyrogram ou le SDK Unipile, et comment gérer les limites de taux sans que votre script ne plante au premier 429. Que vous ayez atterri ici à la recherche d' API bot Telegram Python exemple ou la totalité API Telegram Python illustration, chaque approche ci-dessous est livrée avec du code fonctionnel.



telegram_bot.py
import demandes Jeton = "123456:ABC-your-bot-token" url = f"https://api.telegram.org/bot{TOKEN}/sendMessage" charge utile = { "chat_id": 123456789, "texte": "Bonjour de Python", "mode_analyse": "MarkdownV2" } response = requêtes.poste(url, json=payload) print(réponse.json())
200 OK : message envoyé
Guide de décision

Trois façons de créer l'API Telegram en Python, et laquelle choisir

Une fois que vous disposez de vos identifiants, il existe trois manières concrètes de communiquer avec Telegram à partir d'une base de code Python. Il ne s'agit pas de bibliothèques interchangeables pour la même tâche : chacune s'authentifie comme un type d'expéditeur différent, avec un code et des contraintes différents.
API de bot Telegram pour Python
Un jeton de bot de BotFather, appelé depuis Python avec demandes ou une bibliothèque enveloppe comme python-telegram-bot. La manière la plus rapide d'expédier, mais un bot ne peut envoyer un message à un utilisateur qu'après que celui-ci lui a écrit en premier.
Idéal pour les notifications et les robots de support
Téléthon / Pyrogram (MTProto)
Une bibliothèque cliente Python qui parle le protocole brut de Telegram avec le vôtre id_api et clé d'API. Se connecte avec un vrai compte, mais vous possédez le stockage de session, les reconnexions et le flux d'authentification à deux facteurs (2FA).
Idéal pour un client Python entièrement personnalisé
SDK Python UnipileUnipile
Un compte lié, appelé depuis Python avec quelques lignes de SDK au lieu d'un client MTProto brut. Pas de fichiers de session à persister, pas de branche 2FA à coder soi-même.
Idéal pour expédier rapidement sans posséder MTProto
Cette section concerne le code Python une fois que vous disposez des identifiants. Pour une comparaison complète entre l'API Bot et l'API Client Telegram (limites, identité, ce que chacune peut faire ou ne pas faire), consultez notre comparatif dédié : API du Bot Telegram vs API Telegram. Pour obtenir votre jeton de bot ou id_api / clé d'API en premier lieu, voir le guide d'accès étape par étape.


Intégrez votre solution Python
Tutoriel de code

L'API Python Telegram Bot avec requests

La façon la plus directe d'appeler le API du bot Telegram en Python est un appel HTTP simple avec demandes, sans aucune bibliothèque de wrapper. Depuis l'API Bot 10.2 (14 juillet 2026), un jeton de bot de BotFather et deux paramètres sont tout ce sendMessage nécessite.
1
Obtenez un jeton de bot, puis appelez sendMessage
BotFather émet un jeton en forme de 123456:ABC-your-bot-token. Chaque appel à l'API Bot, y compris sendMessage, est un POST à https://api.telegram.org/bot<TOKEN>/sendMessage avec un corps JSON.



send_message.py
import système d'exploitation import demandes Jeton = os.environ["TELEGRAM_BOT_TOKEN"] URL = f"https://api.telegram.org/bot{TOKEN}/sendMessage" charge utile = { "chat_id": 123456789, "texte": " Votre commande n° #4821 a été expédiée. ", "mode_analyse": "MarkdownV2" } response = requêtes.poste(URL, json=payload, timeout=10)
2
Vérifiez la réponse, ne présumez pas qu'elle a fonctionné
L'API Bot répond toujours avec un corps JSON contenant un d'accord booléen. Un code d'état autre que 200 ou ok : faux signifie que le message n'a pas été envoyé, et la charge utile comprend un texte lisible par l'homme description se connecter.



send_message.py
données = réponse.json() si response.status_code == 200 et données.obtenir("d'accord"): ID du message = données["résultat"]["message_id"] print(f"envoyé, message_id={message_id}") sinon: print(f"échec : {data.get('description')}")
ParamètreTypeDescription
chat_id Requisint ou strIdentifiant de chat cible, ou @username pour une chaîne publique.
text RequischaîneTexte du message, de 1 à 4096 caractères après l'analyse des entités.
mode_analyse FacultatifchaîneMarkdownV2 ou HTML, pour appliquer un formatage en gras, des liens et du code dans le texte.
désactiver_les_notifications FacultatifboolEnvoie le message silencieusement, sans son de notification push.
paramètres_de_réponse FacultatifdictionnaireEnvoie le message en tant que réponse à un message existant dans la discussion.


Dépasser la limite réservée aux bots
Tutoriel de code

L'API du bot Telegram en Python avec python-telegram-bot

Cru demandes les appels fonctionnent bien pour un seul message sortant. Au-delà de cela, la plupart des bases de code Python enveloppent Telegram Bot API en python-telegram-bot, une bibliothèque qui transforme les mêmes points de terminaison HTTP en un objet modèle Python asynchrone avec interrogation des mises à jour intégrée.
Ce que la bibliothèque apporte par rapport à requests brut
Un Application objet qui gère la boucle de mise à jour pour vous (interrogation ou webhook)
Méthodes typées comme bot.send_message() au lieu de charges utiles JSON construites à la main
Gestionnaires de commandes et de messages, donc répondre à /démarrer est un décorateur, pas une boucle
Les paramètres sont les mêmes que ceux traités ci-dessus : chat_id, text, mode_analyse. La bibliothèque ne permet toujours pas à un bot d'envoyer un premier message à un utilisateur, cette restriction relève des règles de la plateforme Telegram, et non du client que vous utilisez pour l'appeler.



bot.py
from telegram import Mettre à jour from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes asynchrone déf commencer(update: Update, context: ContextTypes.DEFAULT_TYPE): await contexte.bot.envoyer_message( chat_id=update.effective_chat.id, Texte="Bonjour de python-telegram-bot", parse_mode="MarkdownV2" ) application = ApplicationBuilder().jeton("123456:ABC-your-bot-token").construire() app.add_handler(Gestionnaire de commandes("début", début)) application.lancer l'écoute()
Client API / MTProto

Un véritable compte utilisateur en Python : Telethon et Pyrogram

Envoyer en tant que véritable compte Telegram depuis Python, et non en tant que bot, signifie passer par l'API Client avec id_api et clé d'API depuis my.telegram.org. Deux bibliothèques Python s'occupent du gros travail MTProto : Telethon et Pyrogram.
Python

Téléthon

Une implémentation MTProto en pur Python construite autour d'async/await, avec une API client qui se lit presque comme du Python ordinaire plutôt que des appels de protocole bruts.
Python

Pyrogram

Un autre client Python MTProto, avec sa propre vision de la gestion des sessions et une interface conçue pour ressembler à un kit de développement (SDK) conventionnel plutôt qu'à une bibliothèque de protocole.



telethon_client.py
from Téléthon import ClientTelegram from telethon.errors import SessionPasswordNeededError id_api = 1234567 clé d'API = "votre_api_hash_de_my.telegram.org" # " my_account " est le nom du fichier de session sur le disque, réutilisé à chaque exécution client = ClientTelegram("mon_compte", api_id, api_hash) asynchrone déf principal(): await client.commencer(téléphone="+15551234567") await client.envoyer_message("nom_utilisateur_ou_id", "Bonjour de Téléthon") avec client : client.loop.exécuter_jusqu_à_complétion(main())
Le mur de la double authentification que chaque système de connexion fait maison doit gérer
1
Envoyez le code de connexion
client.start(phone=...) wraps auth.sendCode, qui envoie un code de connexion par SMS au numéro de téléphone et renvoie un code_hachage_telephone utilisé pour le prochain appel.
2
Valider le code
La bibliothèque demande le code et appelle auth.signIn avec. C'est là qu'une implémentation se contentant du cas nominal s'arrête.
3
SESSION_PASSWORD_NEEDED
Si le compte a l'authentification à deux facteurs activée, Telegram répond par un Erreur 400 : SESSION_PASSWORD_NEEDED. Le Téléthon soulève cette question en tant que SessionPasswordNeededError, une branche attendue, et non un bogue à attraper et ignorer.
4
Validez-le avec le mot de passe du cloud
Transmission du mot de passe cloud du compte à client.start(password=...) exécute l'échange SRP et auth.checkPassword pour vous. Appeler directement la couche MTProto brute signifie construire la VérificationMotDePasseEntréeSRP Objectez-vous.
Persister la session ou se connecter à chaque exécution
Telethon et Pyrogram écrivent tous deux un fichier de session local (ou en mémoire StringSession) après la première connexion réussie. Perdez-le, ou déployez sans le persister, et votre script devra réexécuter le flux du code téléphonique et de la double authentification (2FA) à chaque redémarrage.
Erreurs à prévoir sur ce chemin
MOT_DE_PASSE_DE_SESSION_NECESSAIRE
HACHAGE_DE_MOT_DE_PAS_INVALIDE
API_ID_PUBLISHED_FLOOD
Seules les applications officielles de Telegram bénéficient de l'envoi de codes SMS basé sur Firebase. Un script Python a également besoin du sien id_api depuis my.telegram.org : la réutilisation de l'identifiant d'exemple fourni dans le code source open source déclenche API_ID_PUBLISHED_FLOOD pour vos utilisateurs finaux, et un seul id_api est émis par numéro de téléphone.
L'approche Unipile
Pour obtenir la liste complète des fonctionnalités Telegram prises en charge par Unipile, consultez Page de produit de l'API Telegram.

Un vrai compte Telegram en Python, sans écrire de MTProto

Le SDK Python Unipile connecte un compte utilisateur Telegram existant via le propre Appareils fonctionnalité, soit un scan de code QR, soit une authentification hébergée avec fournisseurs : "TELEGRAM". Il n'y a pas id_api, aucun fichier de session à persister, et aucun MOT_DE_PASSE_DE_SESSION_NECESSAIRE branche à écrire vous-même : le compte associé s'affiche soit comme connecté ou ce n'est pas le cas.
Une fois qu'un compte est lié, l'envoi d'un message depuis Python se résume à quelques appels SDK, le tout s'exécutant sur l'infrastructure d'Unipile v2 API sous-jacente. démarrer_chat prend l'ID du compte associé et un identifiants_utilisateurs liste, et soit ouvre une nouvelle conversation, soit livre dans la conversation existante si un chat existe déjà avec ce destinataire.
Non id_api / clé d'API paire à demander ou à faire pivoter
Pas de fichier de session, pas de poignée de main SRP, pas de branche 2FA dans votre code
Gestion identique du statut de compte pour la gestion des participants aux groupes
L'installation du SDK n'est pas abordée ici, car il est préférable de confirmer le nom exact du paquet par rapport à la documentation actuelle, voir developer.unipile.com/docs/getting-started pour l'étape d'installation et la référence complète de Python.
Toutes les fonctionnalités présentées ici sont répertoriées point de terminaison par point de terminaison sur le Page produit de l'API Telegram Unipile, y compris ce qui est pris en charge et ce qui ne l'est pas.



send_telegram.py
import unipile configuration = unipile.Configuration() configuration.api_key["cléApi"] = "clé d'API" client_api = unipile.ClientApiconfiguration API de messagerie = unipile.API de messagerie(api_client) chat = API de messagerie.démarrer_chat( "acc_123456789", {"identifiants_utilisateurs": ["0123456789"], "texte": "Bonjour, suite à votre demande."} )
Ce que l'intégration Telegram d'Unipile ne couvre pas
Chaînes, communautés et diffusions
Administration du groupe : approbation ou promotion de membres
Archivage des discussions
Appels vocaux et vidéo
Développer avec le SDK Python
Erreurs et limites

Gestion des erreurs et des limites de débit en Python

Un script qui envoie un message dans un chat de test et un script qui s'exécute en production rencontrent des problèmes différents. Le second finit par obtenir un 429 ou un FLOOD_WAIT_X, et ce que fait votre code Python ensuite décide s'il s'agit d'une pause de cinq secondes ou d'un compte banni.
1/s
Nombre maximal de messages de l'API Bot vers la même discussion individuelle
20/min
Nombre maximum de messages de l'API Bot dans un seul groupe
~30/s
Limite approximative de l'API Bot lors de la diffusion à travers les chats
429
Statut renvoyé dès que l'une de ces limites est dépassée
Boucles de nouvelle tentative pour les deux côtés de l'API
L'API Bot et l'API Client signalent le même problème sous deux formes différentes. Toutes deux doivent être interceptées explicitement, et non enregistrées et réessayées aveuglément.



bot_api_retry.py
import temps import demandes déf envoyer_avec_réessai(url, payload, max_retries=3): pour tentative en plage(nombre_tentatives_max) r = requêtes.poste(url, json=payload) si r.status_code != 429: return r réessayer_après = r.json().obtenir("paramètres", {}).obtenir("réessayer_après", 1) temps.Dormir(réessayer_après) soulever Erreur d'exécution("trop de réponses 429")



telethon_flood_wait.py
from telethon.errors import Erreur d'attente d'inondation import asyncio asynchrone déf envoyer_en_toute_securite(client, entité, texte) essayer: await client.envoyer_message(entité, texte) sauf Erreur d'attente d'inondation En tant que e : # e.seconds correspond à la valeur FLOOD_WAIT_X renvoyée par Telegram await asyncio.Dormir(e.seconds) await client.envoyer_message(entité, texte)
Des conseils de rythme qui vous permettent de rester sous les limites dès le départ
Évitez d'envoyer un volume important de comptes flambant neufs, ils sont signalés plus rapidement que les plus établis.
Augmenter le volume d'envoi progressivement au lieu de démarrer un script à plein débit.
Gardez au moins 10 à 20 secondes entre les messages envoyés depuis le même compte, il s'agit de la propre recommandation d'Unipile pour les comptes liés, et non pas seulement d'une limite de l'API Bot.
Résumé

API de bot Telegram Python vs Telethon/Pyrogram vs SDK Unipile

Le même récapitulatif sous forme de tableau : ce que chaque parcours Python exige réellement, et où il s'arrête.
DimensionAPI Bot (requests / python-telegram-bot)Téléthon / Pyrogram (MTProto)SDK Python Unipile
Peut envoyer un message à un utilisateur en premierNonOui, dépendant de la confidentialitéOui,
Exigence d'installationJeton de bot de BotFatherid_api / clé d'API depuis my.telegram.orgCompte lié par code QR ou authentification hébergée
Gestion des sessionsBasé sur les jetons, rien à persisterVous conservez vous-même le fichier de sessionGéré par la fonction Appareils de Telegram
2FA / SESSION_PASSWORD_NEEDEDSans objetVous vous occupez de l'échange SRPPris en charge pour vous
Participants du groupe (obtenir / ajouter / supprimer)Limité aux autorisations du botOui, construit par soi-mêmeOui, des points de terminaison v2 dédiés
Canaux, communautés, diffusionsOui, si ajouté en tant qu'administrateurOui,Non pris en charge
Meilleur pourNotifications et bots de supportUn client MTProto Python entièrement personnaliséExpédier rapidement sans posséder MTProto
Peut envoyer un message à un utilisateur en premier
API de botNon
Téléthon / PyrogramOui, dépendant de la confidentialité
Kit de développement UnipileOui,
Exigence d'installation
API de botJeton de bot
Téléthon / Pyrogramidentifiant d'API / hachage d'API
Kit de développement UnipileCompte lié
Gestion des sessions
API de botRien à persister
Téléthon / PyrogramSession persistée automatiquement
Kit de développement UnipileGéré par les appareils
2FA / SESSION_PASSWORD_NEEDED
API de botSans objet
Téléthon / PyrogramSRP fait maison
Kit de développement UnipilePris en charge pour vous
Participants du groupe (obtenir / ajouter / supprimer)
API de botLimité aux autorisations du bot
Téléthon / PyrogramAutoconstruit
Kit de développement UnipilePoints de terminaison v2 dédiés
Canaux, communautés, diffusions
API de botOui, en tant qu'administrateur
Téléthon / PyrogramOui,
Kit de développement UnipileNon pris en charge
Meilleur pour
API de botNotifications, bots de support
Téléthon / PyrogramClient entièrement personnalisé
Kit de développement UnipileExpédition rapide, pas de MTProto

FAQ sur l'API Telegram en Python

Questions fréquentes sur l'API Python Telegram Bot, python-telegram-bot, Telethon, Pyrogram, et la connexion d'un vrai compte avec Unipile.

Oui. Le Telegram Bot API est une interface HTTP simple, donc un seul POST avec Python demandes bibliothèque vers https://api.telegram.org/bot<TOKEN>/sendMessage, avec un chat_id et text dans le corps de la requête JSON, c'est suffisant. Aucun kit de développement (SDK) ni bibliothèque enveloppe n'est requis pour cet appel.

Le Telegram Bot API est la propre interface HTTP de Telegram, appelable depuis Python avec demandes ou tout client HTTP. python-telegram-bot est une bibliothèque Python tierce qui encapsule ces mêmes points de terminaison HTTP dans un modèle d'objet asynchrone, avec un Application de classe, des méthodes typées telles que bot.send_message, et la vérification des mises à jour intégrée ou la gestion des webhooks.

Il s'agit d'une règle structurelle de l'API Bot, et non d'un bug dans votre code. Un bot ne peut pas appeler sendMessage contre un chat_id jusqu'à ce que cet utilisateur ait envoyé au moins un message au bot au préalable. Aucun paramètre ni bibliothèque Python ne contourne ce problème. Un véritable compte Telegram lié, via Telethon, Pyrogram ou le Kit de développement Unipile, n'a pas cette restriction.

Non. L'API Bot a uniquement besoin d'un jeton de bot émis par BotFather. id_api et clé d'API de my.telegram.org sont requis pour l'API client (MTProto), le protocole utilisé par Telethon, Pyrogram, et tout client qui se connecte en tant que véritable compte utilisateur au lieu d'un bot.

MOT_DE_PASSE_DE_SESSION_NECESSAIRE est une erreur 400 que Telegram renvoie depuis auth.signIn lorsque l'authentification à deux facteurs est activée pour le compte. Telethon déclenche une exception de type SessionPasswordNeededError. L'effacer signifie exécuter le protocole SRP et appeler auth.checkPassword avec le mot de passe cloud du compte, que Telethon et Pyrogram gèrent tous deux lorsque vous passez le mot de passe à leur méthode de connexion.

L'API Bot renvoie un 429 statut une fois que vous dépassez environ un message par seconde vers la même discussion, 20 messages par minute dans un groupe, ou environ 30 messages par seconde lors de la diffusion dans plusieurs discussions. La réponse comprend un réessayer_après valeur en secondes. Du côté de MTProto, l'équivalent est un 420 INONDATION erreur ou un FLOOD_WAIT_X exception, où X est le nombre de secondes à attendre avant de réessayer.

Oui. Le SDK Python Unipile connecte un compte d'utilisateur Telegram existant via la propre fonction Appareils de Telegram, soit par un scan de code QR, soit par authentification hébergée, et expose la messagerie via quelques appels de SDK tels que démarrer_chat. Il n'y a pas id_api à demander, pas d'implémentation MTProto, et pas de fichier de session ou de branche 2FA à écrire soi-même.

La gestion des participants au groupe est prise en charge : lister, ajouter et supprimer des participants via des canaux dédiés v2 points de terminaison. Les canaux, communautés, diffusions, actions d'administration de groupe telles que l'approbation ou la promotion de membres, l'archivage de discussions et les appels vocaux ou vidéo ne sont pas pris en charge.

Vous avez encore des questions ? Notre équipe est là pour vous aider.

Parler à un expert
API Telegram en Python, de la bonne manière

Développez votre intégration de l'API du bot Telegram en Python avec Unipile

Oubliez les fichiers de session MTProto, oubliez la limitation réservée aux bots. Connectez un compte Telegram existant via le SDK Python d'Unipile et unifiez-le avec WhatsApp, LinkedIn, Instagram, Gmail, Outlook et IMAP en une seule API.
fr_FRFR