Crea ora

API di Telegram con Python: Bot API, MTProto e Account Collegati

Guida all'implementazione in Python

Il API di Telegram Python guida: codice funzionante per ogni approccio

Una guida pratica basata sul codice del API di Python Telegram Botil sendMessage chiama con richieste, un bot minimale con python-telegram-bot, un account reale collegato con Telethon, Pyrogram o l'SDK di Unipile, e come gestire i limiti di frequenza senza che il tuo script si blocchi al primo 429. Sia che tu sia arrivato qui in cerca di API bot Telegram Python esempio o il completo API di Telegram Python ogni approccio di seguito viene fornito con codice funzionante.


Costruire con Unipile


Leggi la documentazione



telegram_bot.py
import richieste TOKEN = "123456:ABC-your-bot-token" url = f"https://api.telegram.org/bot{TOKEN}/sendMessage" carico utile = { "chat_id": 123456789, "testo": "Ciao da Python", "parse_mode": "MarkdownV2" } response = richieste.posta(url, json=payload) print(risposta.json())
200 OK: messaggio inviato
Guida alle decisioni

Tre modi per costruire l'API di Telegram in Python e quale scegliere

Una volta ottenute le credenziali, ci sono tre modi concreti per comunicare con Telegram da una base di codice Python. Non sono librerie interscambiabili per lo stesso compito: ciascuna si autentica come un diverso tipo di mittente, con codice e vincoli differenti.
API di Python Telegram Bot
Un token bot di BotFather, chiamato da Python con richieste o una libreria wrapper come python-telegram-bot. Il modo più veloce per spedire, ma un bot può inviare un messaggio a un utente solo se questo gli ha scritto per primo.
Ideale per notifiche e bot di supporto
Telethon / Pyrogram (MTProto)
Una libreria client Python che comunica con il protocollo Telegram grezzo con il proprio api_id e api_hash. Si collega come un account reale, ma tu possiedi l'archiviazione della sessione, le riconnessioni e il flusso dell'autenticazione a due fattori (2FA).
Il migliore per un client Python completamente personalizzato
SDK Python di UnipileUnipile
Un account collegato, richiamato da Python con poche righe di SDK anziché un client MTProto grezzo. Nessun file di sessione da persistere, nessun ramo 2FA da scrivere autonomamente.
Il meglio per spedire velocemente senza possedere MTProto
Questa sezione riguarda il codice Python una volta ottenute le credenziali. Per l'arbitraggio completo tra la Bot API e la Telegram Client API (limiti, identità, ciò che ciascuna può e non può fare), consulta il nostro confronto dedicato: Telegram Bot API contro Telegram API. Per ottenere il token del tuo bot o api_id / api_hash innanzitutto, guarda il guida di accesso passo-passo.


Crea la tua integrazione in Python
Tutorial di codice

L'API di Python Telegram Bot con requests

Il modo più diretto per chiamare il API di Telegram Bot in Python è una chiamata HTTP in chiaro con richieste, senza alcuna libreria di supporto. A partire dalle Bot API 10.2 (14 luglio 2026), un token bot di BotFather e due parametri sono tutto ciò sendMessage richiede.
1
Ottieni un token per bot, quindi chiama sendMessage
BotFather emette un token fatto a forma di 123456:ABC-your-bot-token. Ogni chiamata alle API dei Bot, inclusi sendMessage, è un POSTA a https://api.telegram.org/bot<TOKEN>/sendMessage con un corpo JSON.



send_message.py
import os import richieste TOKEN = os.circa["TELEGRAM_BOT_TOKEN"] URL = f"https://api.telegram.org/bot{TOKEN}/sendMessage" carico utile = { "chat_id": 123456789, "testo": ""Il tuo ordine #4821 è stato spedito."", "parse_mode": "MarkdownV2" } response = richieste.posta(URL, json=payload, timeout=10)
2
Controlla la risposta, non dare per scontato che abbia funzionato
L'API Bot risponde sempre con un corpo JSON contenente un va bene booleano. Un codice di stato diverso da 200 o ok: false significa che il messaggio non è stato inviato e il carico utile include un testo leggibile dall'uomo descrizione registrare.



send_message.py
dati = risposta.json() se response.status_code == 200 e dati.ottenere("ok"): id_messaggio = dati["risultato"]["ID messaggio"] print(f"inviato, message_id={message_id}") altro: print(f"fallito: {data.get('description')}")
ParametroTipoDescrizione
chat_id Richiestoint o strIdentificatore della chat di destinazione, o @username per un canale pubblico.
text RichiestostradaTesto del messaggio, da 1 a 4096 caratteri dopo l'analisi delle entità.
modalità_analisi OpzionalestradaMarkdownV2 o HTML, per applicare la formattazione in grassetto, ai link e al codice nel testo.
disabilita_notifica OpzionalebooleanoInvia il messaggio in silenzio, senza un suono di notifica push.
parametri_di_risposta OpzionaledizionarioInvia il messaggio come risposta a un messaggio esistente nella chat.


Supera il limite riservato ai soli bot
Tutorial di codice

L'API del bot di Telegram in Python con python-telegram-bot

Crudo richieste le chiamate funzionano bene per un singolo messaggio in uscita. Oltre a ciò, la maggior parte delle codebase Python racchiude API del bot di Telegram in python-telegram-bot, una libreria che trasforma gli stessi endpoint HTTP in un modello a oggetti Python asincrono con polling di aggiornamento integrato.
Cosa aggiunge la libreria rispetto a requests grezzo
Un Applicazione oggetto che gestisce il ciclo di aggiornamento per te (polling o webhook)
Metodi tipizzati come bot.send_message() invece di payload JSON costruiti a mano
Gestori di comandi e messaggi, quindi rispondendo a /avviare è un decoratore, non un ciclo
I parametri sono gli stessi trattati sopra: chat_id, text, modalità_analisi. La libreria non può ancora fare in modo che un bot invii il primo messaggio a un utente; tale restrizione appartiene alle regole della piattaforma di Telegram, non al client che usi per richiamarla.



bot.py
from telegramma import Aggiorna from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes asincrono def inizio(update: Update, context: ContextTypes.DEFAULT_TYPE): await context.bot.invia_messaggio( chat_id=update.effective_chat.id, Testo="Ciao da python-telegram-bot", parse_mode="MarkdownV2" ) app = ApplicationBuilder().gettone("123456:ABC-your-bot-token").costruire() app.add_handler(CommandHandler("inizio", inizia)) app.avvia_polling()
Client API / MTProto

Un vero account utente in Python: Telethon e Pyrogram

Inviare messaggi come un account Telegram reale da Python, e non come un bot, significa passare attraverso la Client API con api_id e api_hash da my.telegram.org. Due librerie Python svolgono il lavoro pesante di MTProto: Telethon e Pyrogram.
Pitone

Telethon

Un'implementazione MTProto in puro Python basata su async/await, con un'API client che risulta simile a Python standard anziché a chiamate di protocollo grezze.
Pitone

Pyrogram

Un altro client Python MTProto, con una propria gestione delle sessioni e un'interfaccia client progettata per somigliare a un SDK convenzionale anziché a una libreria di protocollo.



telethon_client.py
from maratona televisiva import TelegramClient from telethon.errors import SessionPasswordNeededError api_id = 1234567 api_hash = "il_tuo_api_hash_da_my.telegram.org" # "my_account" è il nome del file di sessione su disco, riutilizzato ad ogni esecuzione client = TelegramClient("il_mio_account", api_id, api_hash) asincrono def principale(): await cliente.inizio(telefono="+15551234567") await cliente.invia_messaggio("nome_utente_o_id", "Ciao da Telethon") con cliente: loop del client.esegui_fino_al_completamento(main())
Il muro della 2FA che ogni sistema di login fatto in casa deve gestire
1
Invia il codice di accesso
client.start(phone=...) involucri auth.sendCode, che invia un codice di accesso tramite SMS al numero di telefono e restituisce un hash_codice_telefonico utilizzato per la prossima chiamata.
2
Valida il codice
La libreria richiede il codice e chiama auth.signIn con esso. È qui che si ferma un'implementazione basata solo sul percorso felice.
3
SESSIONE_PASSWORD_NECESSARIA
Se l'account ha l'autenticazione a due fattori abilitata, Telegram risponde con un Errore 400: SESSION_PASSWORD_NEEDED. Telethon solleva questo problema come SessionPasswordNeededError, un ramo atteso, non un bug da intercettare e ignorare.
4
Chiariscilo con la password del cloud
Passaggio della password cloud dell'account a client.start(password=...) esegue lo scambio SRP e auth.checkPassword per te. Chiamare direttamente il livello grezzo di MTProto significa costruire InputCheckPasswordSRP oggettivati.
Salva la sessione o accedi a ogni esecuzione
Telethon e Pyrogram scrivono entrambi un file di sessione locale (o in memoria) StringSession) dopo il primo accesso riuscito. Perdilo, o distribuiscilo senza renderlo persistente, e il tuo script dovrà rieseguire la procedura del codice telefonico e dell'autenticazione a due fattori (2FA) a ogni riavvio.
Errori da aspettarsi su questo percorso
PASSWORD_SESSIONE_NECESSARIA
HASH_PASSWORD_NON_VALIDO
API_ID_PUBBLICATO_FLOOD
Solo le app ufficiali di Telegram ricevono la consegna del codice SMS basata su Firebase. Anche uno script Python ha bisogno della propria api_id da my.telegram.org: il riutilizzo dell'ID di esempio fornito nel codice sorgente open source attiva API_ID_PUBBLICATO_FLOOD per i tuoi utenti finali, e solo uno api_id viene emesso per numero di telefono.
L'approccio Unipile
Per l'elenco completo delle funzionalità di Telegram esposte da Unipile, vedere la Pagina del prodotto Telegram API.

Un vero account Telegram in Python, senza scrivere MTProto

L'SDK Python di Unipile collega un account utente Telegram esistente tramite il protocollo proprietario di Telegram Dispositivi funzionalità, sia una scansione di codice QR che l'Autenticazione Ospitata con fornitori: "TELEGRAM". Non c'è api_id, nessun file di sessione da salvare e nessun PASSWORD_SESSIONE_NECESSARIA ramo in cui scrivere autonomamente: l'account collegato risulta collegato o non lo fa.
Una volta collegato un account, l'invio di un messaggio da Python richiede poche chiamate SDK, il tutto eseguito su Unipile v2 API sottostanti. Avvia chat prende l'ID dell'account collegato e un ID utente elenco, e apre una nuova conversazione o la consegna in quella esistente se esiste già una chat con quel destinatario.
No api_id / api_hash coppia da richiedere o ruotare
Nessun file di sessione, nessun handshake SRP, nessun ramo 2FA nel tuo codice
Gestione dello stato dell'account identica per la gestione dei partecipanti al gruppo
L'installazione dell'SDK non è trattata qui poiché è preferibile confermare il nome esatto del pacchetto rispetto alla documentazione attuale, vedi developer.unipile.com/docs/getting-started per la fase di installazione e il riferimento Python completo.
Ogni funzionalità qui mostrata è elencata endpoint per endpoint sul Pagina prodotto API Telegram di Unipile, compreso ciò che è supportato e ciò che non lo è.



send_telegram.py
import unipilo configurazione = unipilo.Configurazione() configuration.api_key["chiave API"] = "chiave API" client_api = unipilo.ApiClient(configurazione) API di messaggistica = unipilo.API di messaggistica(api_client) chat = API di messaggistica.Avvia chat( "acc_123456789", {"ID utente": ["0123456789"], "testo": "Ciao, in merito alla tua richiesta."} )
Cosa non copre l'integrazione di Telegram di Unipile
Canali, community e trasmissioni
Amministrazione del gruppo: approvazione o promozione dei membri
Archiviazione della chat
Chiamate vocali e video
Crea con l'SDK Python
Errori e limiti

Gestione degli errori e dei limiti di frequenza in Python

Uno script che invia un messaggio in una chat di test e uno script eseguito in produzione incontrano problemi diversi. Il secondo alla fine riceve un 429 oppure un ATTESA_ALLAGAMENTO_X, e ciò che il tuo codice Python farà subito dopo deciderà se si tratterà di una pausa di cinque secondi o di un account bannato.
1/sec
Numero massimo di messaggi dell'API Bot alla stessa chat individuale
20/min
Numero massimo di messaggi dell'API Bot all'interno di un singolo gruppo
~30/sec
Limite approssimativo dell'API dei Bot durante la trasmissione tra le chat
429
Stato restituito una volta superato uno di questi limiti
Cicli di ripetizione per entrambi i lati dell'API
Le API Bot e Client segnalano lo stesso problema con due forme diverse. Entrambe devono essere catturate esplicitamente, non registrate e riprovate ciecamente.



bot_api_retry.py
import tempo import richieste def inviare_con_ritentativo(url, payload, max_retries=3): per tentativo in gamma(max_tentativi): r = richieste.posta(url, json=payload) se r.status_code != 429: return r riprova_dopo = r.json().ottenere("parametri", {}).ottenere("riprova_dopo", 1) tempo.dormire(riprova_dopo) salire Errore di esecuzione("troppe risposte 429")



telethon_flood_wait.py
from telethon.errors import FloodWaitError import asyncio asincrono def invia_in_sicurezza(cliente, entità, testo) tentare: await cliente.invia_messaggio(entità, testo) tranne FloodWaitError come e: # e.seconds è il valore FLOOD_WAIT_X restituito da Telegram await asyncio.dormire(e.seconds) await cliente.invia_messaggio(entità, testo)
Indicazioni di ritmo che ti mantengono comunque entro i limiti
Evita di inviare volumi elevati da account nuovissimi, vengono segnalati più velocemente di quelli consolidati.
Aumentare il volume di invio progressivamente invece di avviare uno script a pieno regime.
Mantieni almeno Da 10 a 20 secondi tra i messaggi inviati dallo stesso account, questa è la raccomandazione di Unipile per gli account collegati, non solo un limite della Bot API.
Riepilogo

API di Python Telegram Bot vs Telethon/Pyrogram vs SDK di Unipile

Lo stesso riepilogo in formato di tabella: cosa richiede effettivamente ciascun percorso in Python e dove si interrompe.
DimensioneBot API (requests / python-telegram-bot)Telethon / Pyrogram (MTProto)SDK Python di Unipile
È possibile inviare un messaggio a un utente per primoNoSì, dipendente dalla privacySì
Requisito di configurazioneToken del bot di BotFatherapi_id / api_hash da my.telegram.orgAccount collegato tramite codice QR o Hosted Auth
Gestione della sessioneBasato su token, nulla da persistereSalvi il file di sessione tu stessoGestito dalla funzione Dispositivi di Telegram
2FA / SESSION_PASSWORD_NEEDEDNon applicabileGestisci tu lo scambio SRPGestito per te
Partecipanti al gruppo (ottieni / aggiungi / rimuovi)Limitato ai permessi del botSì, autocostruitoSì, endpoint v2 dedicati
Canali, community, broadcastSì, se aggiunto come amministratoreSìNon supportato
Il migliore perNotifiche e bot di supportoUn client MTProto in Python completamente personalizzatoSpedire velocemente senza possedere MTProto
È possibile inviare un messaggio a un utente per primo
API BotNo
Telethon / PyrogramSì, dipendente dalla privacy
SDK UnipileSì
Requisito di configurazione
API BotToken del bot
Telethon / Pyrogramapi_id / api_hash
SDK UnipileAccount collegato
Gestione della sessione
API BotNulla da persistere
Telethon / PyrogramSessione autopersistita
SDK UnipileGestito tramite Dispositivi
2FA / SESSION_PASSWORD_NEEDED
API BotNon applicabile
Telethon / PyrogramSRP autocostruito
SDK UnipileGestito per te
Partecipanti al gruppo (ottieni / aggiungi / rimuovi)
API BotLimitato ai permessi del bot
Telethon / PyrogramAutocostruito
SDK UnipileEndpoint v2 dedicati
Canali, community, broadcast
API BotSì, come amministratore
Telethon / PyrogramSì
SDK UnipileNon supportato
Il migliore per
API BotNotifiche, bot di supporto
Telethon / PyrogramClient personalizzato al 100%
SDK UnipileSpedizione veloce, niente MTProto
Costruiscilo con l'SDK di Unipile

API di Telegram in Python - FAQ

Domande frequenti sull'API di Python Telegram Bot, python-telegram-bot, Telethon, Pyrogram e sulla connessione di un account reale con Unipile.

Sì. Il API del bot di Telegram è una semplice interfaccia HTTP, quindi una singola POSTA con requests di Python richieste biblioteca a https://api.telegram.org/bot<TOKEN>/sendMessage, con un chat_id e text nel corpo JSON, è sufficiente. Non è richiesto alcun SDK o libreria wrapper per questa chiamata.

Il API del bot di Telegram è la stessa interfaccia HTTP di Telegram, richiamabile da Python con richieste o qualsiasi client HTTP. python-telegram-bot è una libreria Python di terze parti che incapsula quegli stessi endpoint HTTP in un modello a oggetti asincrono, con un Applicazione metodi di classe tipizzati come bot.send_message, e polling degli aggiornamenti integrato o gestione dei webhook.

Questa è una regola strutturale delle Bot API, non un bug nel tuo codice. Un bot non può chiamare sendMessage contro un chat_id fino a quando quell'utente non ha inviato almeno un messaggio al bot per primo. Nessun parametro o libreria Python aggira il problema. Un vero account Telegram collegato, tramite Telethon, Pyrogram, o il SDK Unipile, non ha questa restrizione.

No. L'API del Bot richiede solo un token del bot emesso da BotFather. api_id e api_hash da my.telegram.org sono richiesti per la Client API (MTProto), il protocollo utilizzato da Telethon, Pyrogram e qualsiasi client che effettua l'accesso come account utente reale anziché come bot.

PASSWORD_SESSIONE_NECESSARIA è un errore 400 restituito da Telegram auth.signIn quando l'account ha l'autenticazione a due fattori abilitata. Telethon solleva un'eccezione come SessionPasswordNeededError. Cancellarlo significa eseguire il protocollo SRP e chiamare auth.checkPassword con la password cloud dell'account, che sia Telethon che Pyrogram gestiscono quando passi la password al loro metodo di accesso.

L'API Bot restituisce un 429 lo stato una volta superato circa un messaggio al secondo nella stessa chat, 20 messaggi al minuto in un gruppo o circa 30 messaggi al secondo durante la trasmissione tra chat. La risposta include un riprova_dopo valore in secondi. Sul lato MTProto, l'equivalente è un 420 FLOOD errore o un ATTESA_ALLAGAMENTO_X eccezione, dove X è il numero di secondi da attendere prima di riprovare.

Sì. Il SDK Python di Unipile collega un account utente Telegram esistente tramite la funzione Dispositivi di Telegram, tramite la scansione di un codice QR o l'autenticazione ospitata, ed espone la messaggistica tramite alcune chiamate SDK come Avvia chat. Non c'è api_id da richiedere, nessuna implementazione MTProto e nessun file di sessione o ramo 2FA da scrivere autonomamente.

La gestione dei partecipanti al gruppo è supportata: elenco, aggiunta e rimozione di partecipanti tramite appositi v2 endpoint. Canali, community, broadcast, azioni di amministrazione dei gruppi come l'approvazione o la promozione dei membri, l'archiviazione delle chat e le chiamate o videochiamate non sono supportati.

Avete ancora domande? Il nostro team è qui per aiutarvi.

Parlare con un esperto
API di Telegram in Python, fatte bene

Costruisci la tua integrazione Python con l'API del bot Telegram utilizzando Unipile

Salta i file di sessione MTProto, salta la limitazione ai soli bot. Connetti un account Telegram esistente tramite l'SDK Python di Unipile e unificalo con WhatsApp, LinkedIn, Instagram, Gmail, Outlook e IMAP in un'unica API.
Costruire con Unipile
Leggi la documentazione Vedi la pagina delle API di Telegram
Ottenere l'accesso all'API di Telegram, passo dopo passo
Invia un messaggio Telegram con l'API
Telegram Bot API contro Telegram API
Pagina prodotto API Telegram di Unipile
it_ITIT
en_USEN fr_FRFR es_ESES de_DEDE pt_BRBR nl_NLNL pl_PLPL tr_TRTR it_ITIT