Le API Telegram Python guide : du code fonctionnel pour chaque approche
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.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())Trois façons de créer l'API Telegram en Python, et laquelle choisir
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_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_api / clé d'API en premier lieu, voir le guide d'accès étape par étape.Intégrez votre solution Python
L'API Python Telegram Bot avec requests
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.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.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)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.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ètre | Type | Description |
|---|---|---|
chat_id Requis | int ou str | Identifiant de chat cible, ou @username pour une chaîne publique. |
text Requis | chaîne | Texte du message, de 1 à 4096 caractères après l'analyse des entités. |
mode_analyse Facultatif | chaîne | MarkdownV2 ou HTML, pour appliquer un formatage en gras, des liens et du code dans le texte. |
désactiver_les_notifications Facultatif | bool | Envoie le message silencieusement, sans son de notification push. |
paramètres_de_réponse Facultatif | dictionnaire | Envoie le message en tant que réponse à un message existant dans la discussion. |
Dépasser la limite réservée aux bots
L'API du bot Telegram en Python avec python-telegram-bot
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.Application objet qui gère la boucle de mise à jour pour vous (interrogation ou webhook)bot.send_message() au lieu de charges utiles JSON construites à la main/démarrer est un décorateur, pas une bouclechat_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.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()Un véritable compte utilisateur en Python : Telethon et Pyrogram
id_api et clé d'API depuis my.telegram.org. Deux bibliothèques Python s'occupent du gros travail MTProto : Telethon et Pyrogram.Téléthon
Pyrogram
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())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. 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. 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. 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. 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. HACHAGE_DE_MOT_DE_PAS_INVALIDE
API_ID_PUBLISHED_FLOOD
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.Un vrai compte Telegram en Python, sans écrire de MTProto
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.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.id_api / clé d'API paire à demander ou à faire pivoterimport 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."}
)Gestion des erreurs et des limites de débit en Python
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.Nombre maximal de messages de l'API Bot vers la même discussion individuelle
Nombre maximum de messages de l'API Bot dans un seul groupe
Limite approximative de l'API Bot lors de la diffusion à travers les chats
Statut renvoyé dès que l'une de ces limites est dépassée
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")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)API de bot Telegram Python vs Telethon/Pyrogram vs SDK Unipile
| Dimension | API Bot (requests / python-telegram-bot) | Téléthon / Pyrogram (MTProto) | SDK Python Unipile |
|---|---|---|---|
| Peut envoyer un message à un utilisateur en premier | Non | Oui, dépendant de la confidentialité | Oui, |
| Exigence d'installation | Jeton de bot de BotFather | id_api / clé d'API depuis my.telegram.org | Compte lié par code QR ou authentification hébergée |
| Gestion des sessions | Basé sur les jetons, rien à persister | Vous conservez vous-même le fichier de session | Géré par la fonction Appareils de Telegram |
| 2FA / SESSION_PASSWORD_NEEDED | Sans objet | Vous vous occupez de l'échange SRP | Pris en charge pour vous |
| Participants du groupe (obtenir / ajouter / supprimer) | Limité aux autorisations du bot | Oui, construit par soi-même | Oui, des points de terminaison v2 dédiés |
| Canaux, communautés, diffusions | Oui, si ajouté en tant qu'administrateur | Oui, | Non pris en charge |
| Meilleur pour | Notifications et bots de support | Un client MTProto Python entièrement personnalisé | Expédier rapidement sans posséder 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.