LinkedIn
Instagram
WhatsApp
Telegram
Gmail
Outlook
Google Agenda
Word lid van de Slack-gemeenschap Inhoudsopgave
Python-implementatiehandleiding
De Telegram API Python handleiding: werkende code voor elke benadering
Een code-first walkthrough van de Python Telegram Bot APIde
sendMessage bellen met verzoekt, een minimale bot met python-telegram-bot, een echt gekoppeld account met Telethon, Pyrogram of de Unipile SDK, en hoe je omgaat met limieten (rate limits) zonder dat je script bij de eerste crasht 429. Of je hier nu bent beland op zoek naar een Telegram bot API Python voorbeeld of de volledige telegram api python afbeelding, elke onderstaande benadering wordt geleverd met werkende code.importeer verzoekt
TOKEN = "123456:ABC-your-bot-token"
url = f"https://api.telegram.org/bot{TOKEN}/sendMessage"
lading = {
"chat_id": 123456789,
"tekst": "Hallo vanuit Python",
"parse_mode": "MarkdownV2"
}
response = verzoeken.post(url, json=payload)
print(antwoord.json())200 OK: bericht verzonden
Beslissingsgids
Drie manieren om de Telegram API te bouwen in Python, en welke je moet kiezen
Zodra u over inloggegevens beschikt, zijn er drie concrete manieren om vanuit een Python-codebasis met Telegram te communiceren. Het zijn geen uitwisselbare bibliotheken voor dezelfde taak: elke bibliotheek the authenticeert als een ander soort afzender, met andere code en andere beperkingen.
Python Telegram Bot API
Een bot-token van BotFather, aangeroepen vanuit Python met
Het beste voor meldingen en supportbots verzoekt of een wrapper-bibliotheek zoals python-telegram-bot. De snelste manier om te verzenden, maar een bot kan alleen een bericht sturen naar een gebruiker die er eerst naar heeft geschreven.Telethon / Pyrogram (MTProto)
Een Python-clientbibliotheek die het onbewerkte Telegram-protocol spreekt met je eigen
Het beste voor een volledig aangepaste Python-client api_id en api_hash. Logt in als een echt account, maar je beheert de sessieopslag, herverbindingen en de 2FA-stroom.Unipile Python SDKEenpaal
Een gekoppeld account, aangeroepen vanuit Python met een paar SDK-regels in plaats van een rauwe MTProto-client. Geen sessiebestanden om te behouden, geen 2FA-tak om zelf te schrijven.
Het beste voor sneller verzenden zonder eigendom van MTProto Dit gedeelte gaat over de Python-code zodra je over inloggegevens beschikt. Voor de volledige afweging tussen de Bot API en de Telegram Client API (limieten, identiteit, wat elk wel en niet kan), zie onze speciale vergelijking: Telegram Bot API vs Telegram API. Voor het verkrijgen van je bot-token of
api_id / api_hash zie in de eerste plaats de stapsgewijze toegangsgids.Bouw je Python-integratie
Code Handleiding
De Python Telegram Bot API met requests
De meest directe manier om te bellen Telegram Bot API in Python is een gewone HTTP-aanroep met
verzoekt, zonder dat hier een wrapper-bibliotheek bij komt kijken. Vanaf Bot API 10.2 (14 juli 2026) zijn een bot-token van BotFather en twee parameters het enige wat sendMessage vereist.1
Ontvang een bottokoken en roep vervolgens sendMessage aan
BotFather geeft een token uit in de vorm van
123456:ABC-your-bot-token. Elke Bot API-aanroep, inclusief sendMessage, is een POST naar https://api.telegram.org/bot<TOKEN>/sendMessage met een JSON-body.importeer os
importeer verzoekt
TOKEN = os.ongeveer["TELEGRAM_BOT_TOKEN"]
URL = f"https://api.telegram.org/bot{TOKEN}/sendMessage"
lading = {
"chat_id": 123456789,
"tekst": ""Uw bestelling #4821 is verzonden."",
"parse_mode": "MarkdownV2"
}
response = verzoeken.post(URL, json=payload, timeout=10)2
Controleer het antwoord, ga er niet vanuit dat het heeft gewerkt
De Bot API antwoordt altijd met een JSON-body die een
oké boolean. Een niet-200 statuscode of ok: false betekent dat het bericht niet is verzonden en de payload een leesbare tekst bevat beschrijving aanmelden.gegevens = antwoord.json()
als response.status_code == 200 en gegevens.krijgen("oké"):
bericht-id = gegevens["resultaat"]["bericht_id"]
print(verzonden, message_id={message_id}")
anders:
print(mislukt: {data.get("description')}')| Parameter | Type | Beschrijving |
|---|---|---|
chat_id Vereist | int of str | Doelchat-id of @username voor een openbaar kanaal. |
text Vereist | straal | Berichttekst, 1 tot 4096 tekens na entiteitparsing. |
parse_mode Optioneel | straal | MarkdownV2 of HTML, om vette, link- en code-opmaak in de tekst weer te geven. |
melding_uitschakelen Optioneel | booleaans | Verzendt het bericht stil, zonder een push-notificatiegeluid. |
antwoordparameters Optioneel | dictee | Verstuurt het bericht als een antwoord op een bestaand bericht in de chat. |
Ga voorbij de limiet voor alleen bots
Code Handleiding
De Telegram Bot API in Python met python-telegram-bot
Rauw
verzoekt oproepen werken prima voor één uitgaand bericht. Degenen die daarna komen, verpakken de meeste Python-codebases in de Telegram Bot API in python-telegram-bot, een bibliotheek die dezelfde HTTP-endpoints omzet in een asynchroon Python-objectmodel met ingebouwde update-polling. Wat de bibliotheek toevoegt ten opzichte van raw requests
Een
Toepassing object dat de updatelus voor je beheert (polling of webhook)Getypeerde methoden zoals
bot.send_message() in plaats van handgeschreven JSON payloadsCommand- en berichthandlers, dus reageren op
/start is een decorator, geen lusDe parameters zijn dezelfde als hierboven besproken:
chat_id, text, parse_mode. De bibliotheek kan nog steeds niet instellen dat een bot eerst een gebruiker een bericht stuurt; die beperking bevindt zich in de platformregels van Telegram, niet in de client die je gebruikt om het aan te roepen.van telegram importeer Bijwerken
van telegram.ext importeer ApplicationBuilder, CommandHandler, ContextTypes
asynchroon def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
wacht op context.bot.bericht_verzenden(
chat_id=update.effective_chat.id,
tekst="Hallo van python-telegram-bot",
parse_mode="MarkdownV2"
)
app = ApplicationBuilder().token("123456:ABC-your-bot-token").bouwen()
app.add_handler(CommandHandler("start", start))
app.polling_starten()Client-API / MTProto
Een echt gebruikersaccount in Python: Telethon en Pyrogram
Verzenden als een echt Telegram-account vanuit Python, en niet als een bot, betekent dat je via de Client API moet gaan met
api_id en api_hash van my.telegram.org. Twee Python-bibliotheken doen het zware MTProto-werk: Telethon en Pyrogram. Python
Telethon
Een pure Python MTProto-implementatie rondom async/await, met een client-API die sterk lijkt op normale Python in plaats van ruwe protocolaanroepen.
Python
Pyrogram
Nog een Python MTProto-client, met een eigen aanpak voor sessiebeheer en een client-interface die ontworpen is om aan te voelen als een conventionele SDK in plaats van een protocolbibliotheek.
van telethon importeer TelegramClient
van telethon.errors importeer SessionPasswordNeededError
api_id = 1234567
api_hash = "je_api_hash_van_my.telegram.org"
# "my_account" is de bestandsnaam van het sessiebestand op de schijf, die bij elke uitvoering opnieuw wordt gebruikt
klant = TelegramClient("mijn_account", api_id, api_hash)
asynchroon def hoofd():
wacht op klant.start(telefoon="+15551234567")
wacht op klant.bericht_verzenden("gebruikersnaam_of_id", "Hallo van Telethon")
met klant:
client.loop.run_until_complete(main())1
Stuur de inlogcode
client.start(phone=...) wraps auth.sendCode, waarmee een inlogcode naar het telefoonnummer wordt gestuurd en een telefoon_code_hash gebruikt voor het volgende gesprek. 2
Valideer de code
De bibliotheek vraagt om de code en roept aan
De bibliotheek vraagt om de code en roept aan
auth.signIn ermee. Hier stopt een implementatie die alleen uit een 'happy path' bestaat. 3
SESSIE_WACHTWOORD_NODIG
Als het account tweefactorauthenticatie ingeschakeld heeft, antwoordt Telegram met een 400-fout: SESSION_PASSWORD_NEEDED. Telethon brengt dit naar voren als
Als het account tweefactorauthenticatie ingeschakeld heeft, antwoordt Telegram met een 400-fout: SESSION_PASSWORD_NEEDED. Telethon brengt dit naar voren als
SessionPasswordNeededError, een te verwachten tak, geen bug om op te vangen en te negeren. 4
Regel het met het cloudwachtwoord
Het doorgeven van het cloudwachtwoord van het account aan
Het doorgeven van het cloudwachtwoord van het account aan
client.start(password=...) voert de SRP-uitwisseling uit en auth.checkPassword voor jou. Het direct aanroepen van de rauwe MTProto-laag betekent het bouwen van de InputCheckPasswordSRP werp jezelf tegen. Sla de sessie op, of log bij elke uitvoering in
Telethon en Pyrogram schrijven beide een lokaal sessiebestand (of een in-memory
Telethon en Pyrogram schrijven beide een lokaal sessiebestand (of een in-memory
StringSession) na de eerste succesvolle aanmelding. Raak het kwijt, of implementeer het zonder het op te slaan, en je script moet bij elke herstart opnieuw de telefooncode- en 2FA-procedure doorlopen. SESSIE_WACHTWOORD_NODIG
ONGELDIGE_WACHTWOORD_HASH
API_ID_PUBLISHED_FLOOD
ONGELDIGE_WACHTWOORD_HASH
API_ID_PUBLISHED_FLOOD
Alleen de eigen officiële apps van Telegram krijgen op Firebase gebaseerde sms-codedelivery. Een Python-script heeft ook zijn eigen nodig
api_id van my.telegram.org: het hergebruiken van de voorbeeld-ID die in open-source voorbeeldcode wordt meegeleverd, activeert API_ID_PUBLISHED_FLOOD voor uw eindgebruikers, en slechts één api_id wordt per telefoonnummer uitgegeven.De Unipile aanpak
Voor de volledige lijst van Telegram-mogelijkheden die door Unipile worden aangeboden, zie de Telegram API-productpagina.
Een echt Telegram-account in Python, zonder MTProto te schrijven
De Unipile Python SDK verbindt een bestaand Telegram-gebruikersaccount via Telegram's eigen Apparaten functie, het scannen van een QR-code of Hosted Auth met
providers: "TELEGRAM". Er is geen api_id, geen sessiebestand om te behouden, en geen SESSIE_WACHTWOORD_NODIG vertakking om zelf te schrijven: het gekoppelde account wordt weergegeven als aangesloten of het gebeurt niet.Zodra een account is gekoppeld, is het verzenden van een bericht vanuit Python een handvol SDK-aanroepen, die allemaal op Unipile's v2 API eronder.
start_chat neemt de ID van het gekoppelde account en een gebruikers-id's lijst, en opent hetzij een nieuw gesprek of levert af in het bestaande als er al een chat bestaat met die ontvanger.Geen
api_id / api_hash koppelen om aan te vragen of te roterenGeen sessiebestand, geen SRP-handdruk, geen 2FA-tak in je code
Zelfde afhandelingsstatus van het account voor het beheer van groepsdeelnemers
Het installeren van de SDK wordt hier niet behandeld aangezien de exacte pakketnaam het beste kan worden gecontroleerd in de huidige documentatie, zie developer.unipile.com/docs/getting-started voor de installatiestap en de volledige Python-referentie.
Elke hier getoonde functionaliteit wordt endpoint per endpoint opgesomd op de Unipile Telegram API-productpagina, inclusief wat wel en niet wordt ondersteund.
importeer eenpaal
configuratie = eenstemmig.Configuratie()
configuration.api_key["apiKey"] = "API-sleutel"
api_client = eenstemmig.ApiClient(configuratie)
berichten-api = eenstemmig.MessagingApi(api_client)
chat = berichten_api.start_chat(
"acc_123456789",
{"gebruiker_ids": ["0123456789"], "tekst": "Hallo, ik kom even terug op je verzoek."}
)Wat de Unipile Telegram-integratie niet dekt
Kanalen, communities en uitzendingen
Groepsbeheer: leden goedkeuren of promoveren
Chat archiveren
Spraak- en videogesprekken
Fouten en limieten
Fouten en limiet op het aantal verzoeken afhandelen in Python
Een script dat één bericht in een testchat verzuurt en een script dat in productie draait, stuiten op verschillende problemen. De tweede krijgt uiteindelijk een
429 of een HOOSBUI_WACHT_X, en wat je Python-code vervolgens doet, bepaalt of dat een pauze van vijf dagen is of een verbannen account. 1/sec
Maximum aantal Bot API-berichten naar dezelfde individuele chat
Maximum aantal Bot API-berichten naar dezelfde individuele chat
20/min
Maximaal aantal Bot API-berichten in een enkele groep
Maximaal aantal Bot API-berichten in een enkele groep
~30/sec
Geschatte limiet van de Bot API bij het uitzenden naar chats
Geschatte limiet van de Bot API bij het uitzenden naar chats
429
Status wordt geretourneerd zodra een van deze limieten wordt overschreden
Status wordt geretourneerd zodra een van deze limieten wordt overschreden
De Bot-API en de Client-API signaleren hetzelfde probleem in twee verschillende vormen. Beide moeten expliciet worden opgevangen, niet blind worden gelogd en opnieuw worden geprobeerd.
importeer tijd
importeer verzoekt
def versturen_met_herhaalpoging(url, payload, max_retries=3):
voor poging in bereikmax_herpogingen:
r = verzoeken.post(url, json=payload)
als r.status_code != 429:
return r
probeer_opnieuw_na = r.json().krijgen("parameters", {}).krijgen("opnieuw_proberen_na", 1)
tijd.slaap(probeer_opnieuw_na)
verhogen RuntimeError("te veel 429-reacties")van telethon.errors importeer FloodWaitError
importeer asyncio
asynchroon def veilig_verzenden(cliënt, entiteit, tekst)
proberen:
wacht op klant.bericht_verzenden(entiteit, tekst)
uitzondering FloodWaitError als e:
# e.seconds is de waarde van FLOOD_WAIT_X die Telegram heeft teruggestuurd
wacht op asyncio.slaap(e.seconden)
wacht op klant.bericht_verzenden(entiteit, tekst) Tempo-advies dat je sowieso onder de limieten houdt
Vermijd het verzenden van grote volumes vanuit gloednieuwe accounts, ze worden sneller gemarkeerd dan gevestigde.
Verzendvolume verhogen geleidelijk in plaats van een script te starten op volledige doorvoer.
Bewaar ten minste 10 tot 20 seconden tussen berichten die vanaf hetzelfde account worden verzonden, is dit de eigen aanbeveling van Unipile voor gekoppelde accounts, en niet alleen een limiet van de Bot API.
Samenvatting
Python Telegram Bot API versus Telethon/Pyrogram versus Unipile SDK
Dezelfde samenvatting in tabelvorm: wat elk Python-pad daadwerkelijk vereist en waar het stopt.
| Afmeting | Bot-API (requests / python-telegram-bot) | Telethon / Pyrogram (MTProto) | Unipile Python SDK |
|---|---|---|---|
| Kan een gebruiker eerst een bericht sturen | Geen | Ja, privacygevoelig | Ja |
| Installatievereiste | Bot-token van BotFather | api_id / api_hash van my.telegram.org | Gekoppeld account via QR-code of gehoste authenticatie |
| Sessiebeheer | Gebaseerd op tokens, niets om te bewaren | Je slaat het sessiebestand zelf op | Beheerd via de functie Apparaten van Telegram |
| 2FA / SESSION_PASSWORD_NEEDED | Niet van toepassing | Jij handelt de SRP-uitwisseling af | Voor u afgehandeld |
| Groepsdeelnemers (ophalen / toevoegen / verwijderen) | Beperkt tot botrechten | Ja, zelfgebouwd | Ja, toegewijde v2-eindpunten |
| Kanalen, communities, uitzendingen | Ja, indien toegevoegd als beheerder | Ja | Niet ondersteund |
| Het beste voor | Meldingen en supportbots | Een volledig aangepaste Python MTProto-client | Sneller verzenden zonder eigenaar te zijn van MTProto |
Kan een gebruiker eerst een bericht sturen
Bot-APIGeen
Telethon / PyrogramJa, privacygevoelig
Unipile SDKJa
Installatievereiste
Bot-APIBot-token
Telethon / Pyrogramapi_id / api_hash
Unipile SDKGekoppeld account
Sessiebeheer
Bot-APINiets te bewaren
Telethon / PyrogramZelf-opgeslagen sessie
Unipile SDKBeheerd via Apparaten
2FA / SESSION_PASSWORD_NEEDED
Bot-APINiet van toepassing
Telethon / PyrogramZelfgebouwde SRP
Unipile SDKVoor u afgehandeld
Groepsdeelnemers (ophalen / toevoegen / verwijderen)
Bot-APIBeperkt tot botrechten
Telethon / PyrogramZelfgebouwd
Unipile SDKDedicated v2-eindpunten
Kanalen, communities, uitzendingen
Bot-APIJa, als beheerder
Telethon / PyrogramJa
Unipile SDKNiet ondersteund
Het beste voor
Bot-APIMeldingen, supportbots
Telethon / PyrogramVolledig aangepaste client
Unipile SDKSnelle verzending, geen MTProto
Telegram API in Python - FAQ
Veelgestelde vragen over de Python Telegram Bot API, python-telegram-bot, Telethon, Pyrogram en het koppelen van een echt account met Unipile.
Ja. De Telegram Bot API is een eenvoudige HTTP-interface, dus een enkele POST verzoek met Python's verzoekt bibliotheek naar https://api.telegram.org/bot<TOKEN>/sendMessage, met een chat_id en text in de JSON-body volstaat. Er is geen SDK of wrapper-bibliotheek vereist voor deze aanroep.
De Telegram Bot API Is de eigen HTTP-interface van Telegram, aanroepbaar vanuit Python met verzoekt of een andere HTTP-client. python-telegram-bot is een Python-bibliotheek van een derde partij die dezelfde HTTP-endpoints omwikkelt in een asynchroon objectmodel, met een Toepassing klasse, getypeerde methoden zoals bot.send_message, en ingebouwde update polling of webhook-afhandeling.
Dit is een structurele regel van de Bot API, geen bug in je code. Een bot kan niet aanroepen sendMessage tegen een chat_id totdat die gebruiker eerst minstens één bericht naar de bot heeft gestuurd. Geen enkele parameter of Python-bibliotheek omzeilt dit. Een echt gekoppeld Telegram-account, via Telethon, Pyrogram, of de Unipile SDK, heeft deze beperking niet.
Nee. De Bot API heeft alleen een bot-token nodig dat is uitgegeven door BotFather. api_id en api_hash van my.telegram.org zijn vereist voor de Client API (MTProto), het protocol dat wordt gebruikt door Telethon, Pyrogram en elke client die inlogt als een echt gebruikersaccount in plaats van een bot.
SESSIE_WACHTWOORD_NODIG is een 400-fout die Telegram retourneert van auth.signIn wanneer tweefactorauthenticatie is ingeschakeld voor het account. Gooit Telethon dit als SessionPasswordNeededError. Dit wissen betekent het uitvoeren van het SRP-protocol en het aanroepen van auth.checkPassword met het cloudwachtwoord van het account, dat zowel Telethon als Pyrogram verwerken wanneer je het wachtwoord doorgeeft aan hun inlogmethode.
De Bot API retourneert een 429 status zodra je ongeveer meer dan één bericht per seconde naar dezelfde chat overschrijdt, 20 berichten per minuut in een groep, of ongeveer 30 berichten per seconde bij het uitzenden naar meerdere chats. Het antwoord bevat een probeer_opnieuw_na waarde in seconden. Aan de MTProto-kant is het equivalente een 420 FLOOD fout of een HOOSBUI_WACHT_X uitzondering, waarbij X het aantal seconden is dat moet worden gewacht voordat het opnieuw wordt geprobeerd.
Ja. De Unipile Python SDK koppelt een bestaand Telegram-gebruikersaccount via Telegrams eigen Apparaten-functie, het scannen van een QR-code of gehoste authenticatie, en stelt berichtenverkeer beschikbaar via een paar SDK-aanroepen zoals start_chat. Er is geen api_id te aanvragen, geen MTProto-implementatie, en geen sessiebestand of 2FA-branch die je zelf moet schrijven.
Groepsdeelnemersbeheer wordt ondersteund: het weergeven, toevoegen en verwijderen van deelnemers via toegewijde v2 endpoints. Kanalen, communities, broadcasts, groepsbeheersacties zoals het goedkeuren of promoveren van leden, chatarchivering en spraak- of videogesprekken worden niet ondersteund.
Heb je nog vragen? Ons team staat klaar om te helpen.
Telegram API Python, goed aangepakt
Bouw je Telegram-bot API Python-integratie met Unipile
Sla de MTProto-sessiebestanden over, sla de beperking tot alleen bots over. Verbind een bestaand Telegram-account via Unipile's Python SDK en verenig dit met WhatsApp, LinkedIn, Instagram, Gmail, Outlook en IMAP in één API.
NL 
EN 
FR 
ES 
DE 
IT 
BR 
PL 
TR