Table des matières

Choose Your Path

01
3 ways to build Telegram in Python

02
Bot API in Python with requests

Bot API In Python

03
Bot API with python-telegram-bot

04
User accounts: Telethon and Pyrogram

Beyond MTProto

05
User accounts with the Unipile SDK

06
Errors and rate limits in Python

Ressources

07
Compare the 3 approachesLe meilleur

FAQ
Questions fréquemment posées

Python Implementation Guide

Le Telegram API Python guide: working code for every approach

Q: Can I send a Telegram message in Python without a library?

Yes. The Telegram Bot API is a plain HTTP interface, so a single POST request with Python's requests library to https://api.telegram.org/bot /sendMessage, with a chat_id and text in the JSON body, is enough. No SDK or wrapper library is required for this call.

Q: What is the difference between the Python Telegram Bot API and python-telegram-bot?

The Telegram Bot API is Telegram's own HTTP interface, callable from Python with requests or any HTTP client. python-telegram-bot is a third-party Python library that wraps those same HTTP endpoints in an async object model, with an Application class, typed methods like bot.send_message, and built-in update polling or webhook handling.

Q: How do I handle Telegram's SESSION_PASSWORD_NEEDED error in Python?

SESSION_PASSWORD_NEEDED is a 400 error Telegram returns from auth.signIn when the account has two-factor authentication enabled. Telethon raises it as SessionPasswordNeededError. Clearing it means running the SRP protocol and calling auth.checkPassword with the account's cloud password, which Telethon and Pyrogram both handle when you pass the password to their login method.

Q: What happens if my Python script exceeds Telegram's rate limits?

The Bot API returns a 429 status once you exceed roughly one message per second to the same chat, 20 messages per minute in a group, or about 30 messages per second when broadcasting across chats. The response includes a retry_after value in seconds. On the MTProto side, the equivalent is a 420 FLOOD error or a FLOOD_WAIT_X exception, where X is the number of seconds to wait before retrying.

Q: Can I use the Telegram API in Python without maintaining an MTProto client?

Yes. The Unipile Python SDK connects an existing Telegram user account through Telegram's own Devices feature, either a QR code scan or Hosted Auth, and exposes messaging through a few SDK calls such as start_chat. There is no api_id to request, no MTProto implementation, and no session file or 2FA branch to write yourself.

Q: Does the Unipile Python SDK support Telegram groups and channels?

Group participant management is supported, listing, adding, and removing participants through dedicated v2 endpoints. Channels, communities, broadcasts, group administration actions like approving or promoting members, chat archiving, and voice or video calls are not supported.

A code-first walkthrough of the Python Telegram Bot API: the sendMessage call with demandes, a minimal bot with python-telegram-bot, a real linked account with Telethon, Pyrogram, or the Unipile SDK, and how to handle rate limits without your script crashing on the first 429. Whether you landed here looking for a telegram bot api python example or the full telegram api python picture, every approach below ships with working code.

Construire avec Unipile

Lire la documentation

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": "Hello from Python",
    "parse_mode": "MarkdownV2"
}

response = requêtes.poste(url, json=payload)
print(réponse.json())

200 OK : message envoyé

Guide de décision

Three ways to build the Telegram API in Python, and which one to pick

Once you have credentials, there are three concrete ways to talk to Telegram from a Python codebase. They are not interchangeable libraries for the same job: each one authenticates as a different kind of sender, with different code and different constraints.

Python Telegram Bot API

A bot token from BotFather, called from Python with demandes or a wrapper library like python-telegram-bot. The fastest way to ship, but a bot can only message a user who has written to it first.

Best for notifications and support bots

Telethon / Pyrogram (MTProto)

A Python client library that speaks the raw Telegram protocol with your own api_id et api_hash. Logs in as a real account, but you own session storage, reconnects and the 2FA flow.

Best for a fully custom Python client

Unipile Python SDKUnipile

A linked account, called from Python with a few SDK lines instead of a raw MTProto client. No session files to persist, no 2FA branch to write yourself.

Best for shipping fast without owning MTProto

This section is about the Python code once you have credentials. For the full arbitration between the Bot API and the Telegram Client API (limits, identity, what each one can and cannot do), see our dedicated comparison: Telegram Bot API vs Telegram API. For getting your bot token or api_id / api_hash in the first place, see the step-by-step access guide.

Build your Python integration

Tutoriel de code

The Python Telegram Bot API with requests

The most direct way to call the Telegram Bot API in Python is a plain HTTP call with demandes, no wrapper library involved. As of Bot API 10.2 (July 14, 2026), a bot token from BotFather and two parameters are all that sendMessage requires.

1

Get a bot token, then call sendMessage

BotFather issues a token shaped like 123456:ABC-your-bot-token. Every Bot API call, including sendMessage, is a POST à https://api.telegram.org/bot<TOKEN>/sendMessage with a JSON body.

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": "Your order #4821 has shipped.",
    "parse_mode": "MarkdownV2"
}

response = requêtes.poste(URL, json=payload, timeout=10)

2

Check the response, don't assume it worked

The Bot API always answers with a JSON body containing an ok boolean. A non-200 status code or ok: false means the message was not sent, and the payload includes a human-readable description to log.

send_message.py

données = réponse.json()

si response.status_code == 200 et données.obtenir("ok"):
    message_id = données["result"]["message_id"]
    print(f"sent, message_id={message_id}")
sinon:
    print(f"failed: {data.get('description')}")

Parameter	Type	Description
`chat_id` Requis	int or str	Target chat identifier, or `@username` for a public channel.
`text` Requis	chaîne	Message text, 1 to 4096 characters after entity parsing.
`parse_mode` Facultatif	chaîne	`MarkdownV2` ou `HTML`, to render bold, links and code formatting in the text.
`disable_notification` Facultatif	bool	Sends the message silently, without a push notification sound.
`reply_parameters` Facultatif	dictionnaire	Sends the message as a reply to an existing message in the chat.

Build past the bot-only limit

Tutoriel de code

The Telegram Bot API in Python with python-telegram-bot

Raw demandes calls work fine for a single outbound message. Past that, most Python codebases wrap the Telegram Bot API en python-telegram-bot, a library that turns the same HTTP endpoints into an async Python object model with built-in update polling.

What the library adds over raw requests

Un Application object that manages the update loop for you (polling or webhook)

Typed methods like bot.send_message() instead of hand-built JSON payloads

Command and message handlers, so replying to /start is a decorator, not a loop

The parameters are the same ones covered above: chat_id, text, parse_mode. The library still cannot make a bot message a user first, that restriction lives in Telegram's platform rules, not in the client you use to call it.

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 context.bot.envoyer_message(
        chat_id=update.effective_chat.id,
        Texte="Hello from python-telegram-bot",
        parse_mode="MarkdownV2"
    )

application = ApplicationBuilder().jeton("123456:ABC-your-bot-token").construire()
app.add_handler(CommandHandler("début", start))
application.run_polling()

Client API / MTProto

A real user account in Python: Telethon and Pyrogram

Sending as a real Telegram account from Python, not a bot, means going through the Client API with api_id et api_hash from my.telegram.org. Two Python libraries do the MTProto heavy lifting: Telethon and Pyrogram.

Python

Telethon

A pure-Python MTProto implementation built around async/await, with a client API that reads close to plain Python rather than raw protocol calls.

Python

Pyrogram

Another Python MTProto client, with its own take on session handling and a client surface designed to feel like a conventional SDK rather than a protocol library.

telethon_client.py

from telethon import TelegramClient
from telethon.errors import SessionPasswordNeededError

api_id = 1234567
api_hash = "your_api_hash_from_my.telegram.org"

# "my_account" is the session file name on disk, reused on every run
client = TelegramClient("my_account", api_id, api_hash)

asynchrone déf principal():
    await client.commencer(phone="+15551234567")
    await client.envoyer_message("username_or_id", "Hello from Telethon")

avec client :
    client.loop.run_until_complete(main())

The 2FA wall every home-built login has to handle

1

Send the login code
client.start(phone=...) wraps auth.sendCode, which texts a login code to the phone number and returns a phone_code_hash used for the next call.

2

Validate the code
The library prompts for the code and calls auth.signIn with it. This is where a happy-path-only implementation stops.

3

Hit SESSION_PASSWORD_NEEDED
If the account has two-factor authentication enabled, Telegram answers with a 400 error: SESSION_PASSWORD_NEEDED. Telethon raises this as SessionPasswordNeededError, an expected branch, not a bug to catch and ignore.

4

Clear it with the cloud password
Passing the account's cloud password to client.start(password=...) runs the SRP exchange and auth.checkPassword for you. Calling the raw MTProto layer directly means building the InputCheckPasswordSRP object yourself.

Persist the session, or log in every run
Telethon and Pyrogram both write a local session file (or an in-memory StringSession) after the first successful login. Lose it, or deploy without persisting it, and your script has to run the phone-code and 2FA flow again on every restart.

Errors to expect on this path

SESSION_PASSWORD_NEEDED
PASSWORD_HASH_INVALID
API_ID_PUBLISHED_FLOOD

Only Telegram's own official apps get Firebase-based SMS code delivery. A Python script also needs its own api_id from my.telegram.org: reusing the example ID shipped in open-source sample code triggers API_ID_PUBLISHED_FLOOD for your end users, and only one api_id is issued per phone number.

The Unipile approach

For the full list of Telegram capabilities exposed by Unipile, see the Telegram API product page.

A real Telegram account in Python, without writing MTProto

The Unipile Python SDK connects an existing Telegram user account through Telegram's own Devices feature, either a QR code scan or Hosted Auth with providers: "TELEGRAM". There is no api_id, no session file to persist, and no SESSION_PASSWORD_NEEDED branch to write yourself: the linked account either shows as connecté or it doesn't.

Once an account is linked, sending a message from Python is a handful of SDK calls, all running on Unipile's v2 API underneath. start_chat takes the linked account's ID and a user_ids list, and either opens a new conversation or delivers into the existing one if a chat already exists with that recipient.

Non api_id / api_hash pair to request or rotate

No session file, no SRP handshake, no 2FA branch in your code

Same account status handling for group participant management

Installing the SDK is not covered here since the exact package name is best confirmed against the current docs, see developer.unipile.com/docs/getting-started for the install step and full Python reference.

Every capability shown here is listed endpoint by endpoint on the Unipile Telegram API product page, including what is supported and what is not.

send_telegram.py

import unipile

configuration = unipile.Configuration()
configuration.api_key["apiKey"] = "apikey"

api_client = unipile.ApiClient(configuration)
messaging_api = unipile.MessagingApi(api_client)

chat = messaging_api.start_chat(
    "acc_123456789",
    {"user_ids": ["0123456789"], "texte": "Hi, following up on your request."}
)

What the Unipile Telegram integration does not cover

Channels, communities and broadcasts

Group administration: approving or promoting members

Chat archiving

Appels vocaux et vidéo

Build with the Python SDK

Errors and limits

Handling errors and rate limits in Python

A script that sends one message in a test chat and a script that runs in production hit different problems. The second one eventually gets a 429 or a FLOOD_WAIT_X, and what your Python code does next decides whether that is a five-second pause or a banned account.

1/sec
Maximum Bot API messages to the same individual chat

20/min
Maximum Bot API messages inside a single group

~30/sec
Approximate Bot API ceiling when broadcasting across chats

429
Status returned once any of these limits is crossed

Retry loops for both sides of the API

The Bot API and the Client API signal the same problem with two different shapes. Both need to be caught explicitly, not logged and retried blindly.

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
        retry_after = r.json().obtenir("parameters", {}).obtenir("retry_after", 1)
        temps.Dormir(retry_after)
    soulever RuntimeError("too many 429 responses")

telethon_flood_wait.py

from telethon.errors import FloodWaitError
import asyncio

asynchrone déf send_safely(client, entity, text):
    essayer:
        await client.envoyer_message(entity, text)
    sauf FloodWaitError En tant que e :
        # e.seconds is the FLOOD_WAIT_X value Telegram sent back
        await asyncio.Dormir(e.seconds)
        await client.envoyer_message(entity, text)

Pacing guidance that keeps you under the limits in the first place

Avoid sending heavy volume from brand-new accounts, they get flagged faster than established ones.

Ramp up sending volume progressively instead of starting a script at full throughput.

Keep at least 10 to 20 seconds between messages sent from the same account, this is Unipile's own recommendation for linked accounts, not just a Bot API ceiling.

Recap

Python Telegram Bot API vs Telethon/Pyrogram vs Unipile SDK

The same recap in table form: what each Python path actually requires, and where it stops.

Dimension	Bot API (requests / python-telegram-bot)	Telethon / Pyrogram (MTProto)	Unipile Python SDK
Can message a user first	Non	Yes, privacy-dependent	Oui,
Setup requirement	Bot token from BotFather	`api_id` / `api_hash` from my.telegram.org	Linked account via QR code or Hosted Auth
Gestion des sessions	Token-based, nothing to persist	You persist the session file yourself	Managed by Telegram's own Devices feature
2FA / SESSION_PASSWORD_NEEDED	Sans objet	You handle the SRP exchange	Pris en charge pour vous
Group participants (get / add / remove)	Limited to bot permissions	Yes, self-built	Yes, dedicated v2 endpoints
Channels, communities, broadcasts	Yes, if added as admin	Oui,	Non pris en charge
Meilleur pour	Notifications and support bots	A fully custom Python MTProto client	Shipping fast without owning MTProto

Can message a user first

Bot APINon

Telethon / PyrogramYes, privacy-dependent

Unipile SDKOui,

Setup requirement

Bot APIBot token

Telethon / Pyrogramapi_id / api_hash

Unipile SDKLinked account

Gestion des sessions

Bot APINothing to persist

Telethon / PyrogramSelf-persisted session

Unipile SDKManaged via Devices

2FA / SESSION_PASSWORD_NEEDED

Bot APISans objet

Telethon / PyrogramSelf-built SRP

Unipile SDKPris en charge pour vous

Group participants (get / add / remove)

Bot APILimited to bot permissions

Telethon / PyrogramSelf-built

Unipile SDKDedicated v2 endpoints

Channels, communities, broadcasts

Bot APIYes, as admin

Telethon / PyrogramOui,

Unipile SDKNon pris en charge

Meilleur pour

Bot APINotifications, support bots

Telethon / PyrogramFully custom client

Unipile SDKShipping fast, no MTProto

Build it with the Unipile SDK

Telegram API in Python - FAQ

Common questions about the Python Telegram Bot API, python-telegram-bot, Telethon, Pyrogram, and connecting a real account with Unipile.

01
Can I send a Telegram message in Python without a library?

Oui. Le Telegram Bot API is a plain HTTP interface, so a single POST request with Python's demandes library to https://api.telegram.org/bot<TOKEN>/sendMessage, with a chat_id et text in the JSON body, is enough. No SDK or wrapper library is required for this call.

02
What is the difference between the Python Telegram Bot API and python-telegram-bot?

Le Telegram Bot API is Telegram's own HTTP interface, callable from Python with demandes or any HTTP client. python-telegram-bot is a third-party Python library that wraps those same HTTP endpoints in an async object model, with an Application class, typed methods like bot.send_message, and built-in update polling or webhook handling.

03
Why can't my Python Telegram bot message a user who never wrote to it?

This is a structural rule of the Bot API, not a bug in your code. A bot cannot call sendMessage against a chat_id until that user has sent at least one message to the bot first. No parameter or Python library works around it. A real linked Telegram account, through Telethon, Pyrogram, or the Unipile SDK, does not have this restriction.

04
Do I need api_id and api_hash for the Python Telegram Bot API?

No. The Bot API only needs a bot token issued by BotFather. api_id et api_hash from my.telegram.org are required for the Client API (MTProto), the protocol used by Telethon, Pyrogram, and any client that logs in as a real user account instead of a bot.

05
How do I handle Telegram's SESSION_PASSWORD_NEEDED error in Python?

SESSION_PASSWORD_NEEDED is a 400 error Telegram returns from auth.signIn when the account has two-factor authentication enabled. Telethon raises it as SessionPasswordNeededError. Clearing it means running the SRP protocol and calling auth.checkPassword with the account's cloud password, which Telethon and Pyrogram both handle when you pass the password to their login method.

06
What happens if my Python script exceeds Telegram's rate limits?

The Bot API returns a 429 status once you exceed roughly one message per second to the same chat, 20 messages per minute in a group, or about 30 messages per second when broadcasting across chats. The response includes a retry_after value in seconds. On the MTProto side, the equivalent is a 420 FLOOD error or a FLOOD_WAIT_X exception, where X is the number of seconds to wait before retrying.

07
Can I use the Telegram API in Python without maintaining an MTProto client?

Oui. Le Unipile Python SDK connects an existing Telegram user account through Telegram's own Devices feature, either a QR code scan or Hosted Auth, and exposes messaging through a few SDK calls such as start_chat. There is no api_id to request, no MTProto implementation, and no session file or 2FA branch to write yourself.

08
Does the Unipile Python SDK support Telegram groups and channels?

Group participant management is supported: listing, adding, and removing participants through dedicated v2 endpoints. Channels, communities, broadcasts, group administration actions like approving or promoting members, chat archiving, and voice or video calls are not supported.

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

Parler à un expert

Telegram API Python, done right

Build your telegram bot api python integration with Unipile

Skip the MTProto session files, skip the bot-only limitation. Connect an existing Telegram account through Unipile's Python SDK and unify it with WhatsApp, LinkedIn, Instagram, Gmail, Outlook and IMAP in one API.

Construire avec Unipile
Lire la documentation See the Telegram API page

Getting Telegram API access, step by step
Send a Telegram message with the API
Telegram Bot API vs Telegram API
Unipile Telegram API product page

Telegram API with Python: Bot API, MTProto and Linked Accounts

Le Telegram API Python guide: working code for every approach

Three ways to build the Telegram API in Python, and which one to pick

The Python Telegram Bot API with requests

The Telegram Bot API in Python with python-telegram-bot

A real user account in Python: Telethon and Pyrogram

Telethon

Pyrogram

A real Telegram account in Python, without writing MTProto

Handling errors and rate limits in Python

Python Telegram Bot API vs Telethon/Pyrogram vs Unipile SDK

Telegram API in Python - FAQ

Build your telegram bot api python integration with Unipile

Intégrez
en 2 jours

Vidéo de démarrage rapide

Guides de l'Unipile

Rejoignez notre communauté

Entreprise

Produits

Cas d'usage

Solutions

Développeurs

Ressources

Telegram API with Python: Bot API, MTProto and Linked Accounts

Le Telegram API Python guide: working code for every approach

Three ways to build the Telegram API in Python, and which one to pick

The Python Telegram Bot API with requests

The Telegram Bot API in Python with python-telegram-bot

A real user account in Python: Telethon and Pyrogram

Telethon

Pyrogram

A real Telegram account in Python, without writing MTProto

Handling errors and rate limits in Python

Python Telegram Bot API vs Telethon/Pyrogram vs Unipile SDK

Telegram API in Python - FAQ

Build your telegram bot api python integration with Unipile

Intégrezen 2 jours

Vidéo de démarrage rapide

Guides de l'Unipile

Rejoignez notre communauté

Entreprise

Produits

Cas d'usage

Solutions

Développeurs

Ressources

Intégrez
en 2 jours