Crea ora

Telegram Bot API vs Telegram API: Quale ti serve?

Telegram Bot API contro Telegram API

Telegram Bot API vs Telegram API: Quale ti serve?

Il API del bot di Telegram e il API di Telegram (chiamata anche API utente di Telegram, basata su MTProto) risolvono problemi diversi. Una gestisce un account bot tramite HTTP. L'altra gestisce un account utente reale tramite un protocollo binario che devi implementare tu stesso. Questa guida analizza dove ciascuna di esse ti blocca, endpoint per endpoint, e cosa costa realmente sviluppare e mantenere un client dell'API utente di Telegram rispetto al connettere un account esistente tramite Unipile.
Costruire con Unipile
Vedi la documentazione

can-i-message-first.js
// Bot API: bloccato, l'utente non ha mai inviato un messaggio al bot const res = await bot.sendMessage(ID utente, "Ciao"); // -> 403 Forbidden: il bot è stato bloccato dall'utente o non ha mai iniziato una conversazione // Telegram User API tramite Unipile: funziona, è un account reale // POST /v2/:account_id/chats/send const chat = await unipilo.chat.create({ account_id: telegramAccountId, ID utente: [nome utente], text: "Ciao" });
chat.status: "inviato"
I due modelli

API per Bot di Telegram vs API per Utenti di Telegram, in un'unica tabella

Se sai già che Telegram ha più API e vuoi solo sapere quale si applica al tuo progetto, questa tabella ti ci porta in dieci secondi. Se hai ancora bisogno del quadro completo di tutte e tre le API di Telegram, leggi la guida introduttiva Primo. Qui andiamo un livello più in fondo sui due che le persone utilizzano effettivamente per sviluppare: la Bot API e la Telegram User API.
CriteriAPI del bot di TelegramAPI utente di Telegram (MTProto)
Cosa collegaUn account bot, creato e di proprietà della tua appUn vero account utente di Telegram, associato a un numero di telefono
ProtocolloHTTP standard, richieste e risposte JSONMTProto, un protocollo binario personalizzato che implementi
CredenzialiUn token di bot emesso da @BotFatherapi_id + api_hash from my.telegram.org
Identità nelle chatMostra un badge "bot" visibile, distinto da una personaIndistinguibile da una persona che usa l'app
Chi può inviare messaggi a chiIl bot può rispondere solo dopo che un utente ha avviato la chatL'account può inviare messaggi a chiunque, come qualsiasi utente di Telegram
Implementazione tipicaQualsiasi client HTTP, SDK ufficiali e della communityTelethon, Pyrogram, GramJS, TDLib o un account collegato tramite Unipile
CostoGratuitoGratuito da usare, solo il costo dell'infrastruttura self-hosted
API del bot di Telegram
Si collegaUn account bot
ProtocolloHTTP, JSON
CredenzialiToken del bot (BotFather)
IdentitàBadge del bot visibile
A chi può inviare messaggiSolo gli utenti che hanno scritto per primi
CostoGratuito
API utente di Telegram (MTProto)
Si collegaUn account utente reale
ProtocolloMTProto, binario
Credenzialiapi_id + api_hash
IdentitàIndistinguibile da una persona
A chi può inviare messaggiChiunque, come un utente normale
CostoGratuito, self-hosted, solo costo
Crea la tua integrazione con Telegram
La questione che decide

A chi vuoi scrivere per primo?

Qualsiasi altra differenza tra l'API dei bot di Telegram e l'API utente di Telegram è secondaria rispetto a questa. Rispondi prima a questo e il resto di questa guida diventerà una checklist, non una decisione.
Un bot non può iniziare una conversazione con un utente che non gli ha mai scritto per primo
Questa è una regola della piattaforma Telegram, non una limitazione di Unipile o un bug della libreria. Un account bot può rispondere solo all'interno di una chat che l'utente ha già aperto, o dopo che l'utente ha toccato un t.me deep link o si unisce a un gruppo in cui è presente il bot. Se il vostro caso d'uso richiede di contattare qualcuno che non ha ancora interagito con il vostro bot, l'API del Bot non è un'opzione, indipendentemente dal framework o dalla libreria che vi sta sopra.
L'API Bot funziona

L'utente parla prima al tuo bot

Bot di supporto, strumenti basati su comandi, consensi per le notifiche, chatbot collegati dal vostro prodotto. L'utente trova il vostro bot, avvia la chat e da quel momento in poi tutto è un normale scambio che la Bot API gestisce bene.
API del bot bloccata

Devi fare tu il primo passo

Ricerca di vendite, reclutamento, messaggistica per i clienti collegata a un elenco di contatti esistente o qualsiasi flusso di lavoro in cui il tuo prodotto avvia il contatto con un utente di Telegram. Ciò richiede un account utente reale, il che significa l'API utente di Telegram (MTProto), non l'API Bot.
Matrice delle capacità

Cosa funziona davvero, endpoint per endpoint

Al di là della differenza nei titoli, ecco dove ogni opzione vi blocca nella pratica. "Telegram User API (raw)" indica un client MTProto autoprogettato con una libreria come Telethon, Pyrogram, GramJS o TDLib. "Unipile" indica lo stesso account utente reale, connesso senza scrivere codice MTProto in prima persona.
CapacitàAPI BotAPI Utente Telegram (raw)Unipile
Inizia una chat con un utente che non ha mai scritto per primoNoSì, in base alle impostazioni sulla privacy dell'utenteSì, stessa regola di qualsiasi account Telegram
Inviare e ricevere messaggi di testoSì, nelle chat di cui il bot fa parteSìSì
Leggi la cronologia dei messaggi precedente all'ingresso del botNoSìSì
Elenco dei partecipanti al gruppo, aggiungi, rimuoviLimitato ai permessi del botSì, se lo costruisciSì, getParticipantsList, addParticipant, removeParticipant
Amministrazione del gruppo: approva, promuovi, revocaSì, solo se il bot è un amministratoreSì, se lo costruisciNon supportato
Canali, community, broadcastSì, se aggiunto come amministratoreSìNon supportato
Chat segreteNon applicabileSì, se lo costruisciNon supportato
Contatto, posizione, sondaggio, allegati di eventiSìSìNon supportato
Chiamate vocali e videoNoPossibile, alto sforzo di implementazioneNon supportato
Tema della chat, archiviazione, eliminazione della chatNon applicabileSì, se lo costruisciNon supportato
Identità dell'accountIdentità del bot separata, badge visibileIdentità utente reale, associata a numero di telefonoIdentità utente reale, il tuo account esistente
Gestione delle sessioni e dei dispositiviBasato su token, nessun concetto di dispositivoGestisci tu stesso la chiave di autenticazione MTProto e l'autenticazione a due fattori (2FA)Gestito tramite la funzione Dispositivi di Telegram
Inizia una chat a freddo
API BotNo
API utente (non elaborata)Sì, dipendente dalla privacy
UnipileSì
Cronologia dei messaggi precedenti all'accesso
API BotNo
API utente (non elaborata)Sì
UnipileSì
Partecipanti al gruppo (ottieni / aggiungi / rimuovi)
API BotLimitato ai permessi del bot
API utente (non elaborata)Sì, autocostruito
UnipileSì, endpoint dedicati
Amministrazione del gruppo
API BotSì, se bot amministratore
API utente (non elaborata)Sì, autocostruito
UnipileNon supportato
Canali, community, broadcast
API BotSì, come amministratore
API utente (non elaborata)Sì
UnipileNon supportato
Chat segrete
API BotNon applicabile
API utente (non elaborata)Sì, autocostruito
UnipileNon supportato
Allegati di contatti, posizione, sondaggi o eventi
API BotSì
API utente (non elaborata)Sì
UnipileNon supportato
Chiamate vocali e video
API BotNo
API utente (non elaborata)Possibile, grande impegno
UnipileNon supportato
Gestione sessioni / dispositivi
API BotBasato su token
API utente (non elaborata)Chiave di autenticazione gestita autonomamente + 2FA
UnipileLa funzione Dispositivi di Telegram
Cosa non copre Unipile su Telegram
Canali, community e trasmissioni, tema della chat, chat segrete, contatti, posizione, allegati di sondaggi ed eventi, amministrazione dei gruppi (approvazione, promozione, revoca), eliminazione delle chat, archiviazione e chiamate vocali o video. Se il tuo progetto richiede una qualsiasi di queste funzioni, solo un client API utente di Telegram autocostruito copre l'intera gamma.
Costruiscilo con Unipile
Il costo reale

Il vero costo di costruire su MTProto

L'API Utente di Telegram è gratuita, ma il termine "gratuito" copre solo la licenza. Creare e mantenere autonomamente un client per l'API Utente di Telegram comporta un reale costo di ingegneria che un'integrazione con l'API Bot non ha mai. Ecco qual è realmente questo costo.
01

Gestione della sessione e della chiave di autenticazione

MTProto è un protocollo binario, non REST. Tu implementi lo schema TL, lo scambio della chiave di autenticazione e salvi la sessione risultante per conto tuo. Perdi la sessione e l'utente deve riautenticarsi da zero.
02

Autenticazione a due fattori

Gli account con password cloud richiedono la gestione del flusso di autenticazione a due fattori (2FA) basato su SRP di Telegram durante il login. È una macchina a stati in più da costruire, testare e mantenere funzionante a ogni aggiornamento del protocollo Telegram.
03

Un api_id per numero di telefono

api_id e api_hash sono emessi su my.telegram.org sotto "strumenti di sviluppo API" e richiedono un account Telegram attivo. Telegram consente un singolo api_id per numero di telefono, che modella il modo in cui fornisci le credenziali di test e di produzione.
04

Conti sotto osservazione automatica

I client non ufficiali sono sottoposti a osservazione automatica da parte di Telegram. Flood, spam e gonfiaggio artificiale dei contatori possono causare un blocco permanente, il che significa che la limitazione della frequenza (rate limiting) e il riscaldamento (warm-up) sono responsabilità tua, non predefinite della libreria.

shared-api-id-in-open-source.log
// Copia-incolla di un api_id di esempio da un repository open source // invece di registrare il tuo su my.telegram.org Errore: API_ID_PUBBLICATO_FLOOD // Segnala i valori di api_id di Telegram pubblicati in codice pubblico. Ogni applicazione che rilasci ha bisogno del proprio api_id / api_hash, // uno per numero di telefono, altrimenti gli utenti finali incontreranno questo errore.
Salta il lavoro di protocollo
Nulla di tutto ciò è richiesto per collegare un account Telegram reale
Unipile gestisce per te la sessione MTProto, il flusso di accesso e il ciclo di vita delle credenziali. Ottieni un account Telegram reale e umano connesso al tuo prodotto senza scrivere un client da zero.
Inizia a costruire invece
La terza via

Collega un account esistente, salta la build di MTProto

La maggior parte dei team in realtà non vuole creare un client Telegram. Vogliono le funzionalità di un vero account utente: avviare conversazioni, leggere la cronologia completa, gestire i partecipanti ai gruppi, senza possedere un'implementazione di protocollo binario. Questo è ciò che di Unipile API di Telegram è per.
Connettiti tramite la funzione Dispositivi di Telegram
Unipile collega un account utente Telegram esistente tramite la funzione Dispositivi di Telegram, lo stesso meccanismo che consente di accedere a Telegram Desktop o Telegram Web. L'accesso avviene tramite codice QR o tramite Autenticazione Ospitata con fornitori: "TELEGRAM" per un flusso di connessione immediata.
Nessun api_id, nessun api_hash, nessun MTProto da scrivere
Non gestisci mai direttamente lo scambio di chiavi di autenticazione, lo schema TL o la 2FA. L'account collegato si comporta come un vero utente di Telegram perché lo è, non un bot e non un client simulato.
Partecipanti al gruppo, tramite endpoint dedicati
ottieniElencoPartecipanti, aggiungiPartecipante, rimuoviPartecipante, esposto tramite POSTA, GET, e DELETE /v2/{account_id}/chats/{chat_id}/participants. Nessuna chiamata MTProto personalizzata da scrivere per la gestione dell'abbonamento di base.
Stato della sessione associato all'elenco dei dispositivi di Telegram
Se il dispositivo Unipile viene rimosso dalle sessioni attive dell'account all'interno di Telegram, lo stato dell'account passa a disconnesso. Il ciclo di vita della sessione è visibile e prevedibile, non una scatola nera che debugghi da solo.
Crea la tua funzionalità di Telegram
Esplora l'API di Telegram

collega-account-telegram.js
Collega un account utente Telegram esistente // tramite Hosted Auth, nessun codice MTProto richiesto const collegamento = await unipilo.autenticazione gestita.create({ fornitori ["TELEGRAMMA"], scadeil "2026-12-31T23:59:59.000Z" }); // L'utente scansiona il codice QR con l'app Telegram // Lo stato dell'account diventa "connesso" // GET /v2/{account_id}/chats/{chat_id}/participants const membri = await unipilo.chat.ottieniElencoPartecipanti(ID chat);
account.status: "connesso"
Stesse regole, nessuna scorciatoia per aggirarle
Un account collegato è pur sempre un account di Telegram e segue i limiti propri di Telegram: evitare account nuovi di zecca per un uso intenso, aumentare gradualmente il volume e mantenere almeno 10-20 secondi tra un messaggio e l'altro. Vedere il Guida alle API di Telegram e il guida all'invio dei messaggi per la configurazione completa.
Albero di decisione

Qual è quella giusta per il tuo caso

Tre domande, in ordine. Fermati alla prima che corrisponde al tuo progetto.
1
L'utente ti manda sempre il messaggio per primo e il bot deve solo rispondere ai comandi e ai messaggi?
->Bot di supporto, notifiche opt-in, strumenti di comando in cui l'utente avvia il contatto.API Bot
2
Devi contattare tu per primo e ti servono anche canali, chat segrete, amministrazione di gruppi o chiamate?
->Copertura completa della piattaforma, e siete disposti a creare e mantenere il vostro client MTProto con Telethon, Pyrogram, GramJS o TDLib.API utente di Telegram, autocostruita
3
Devi contattare per primo, comportarti come un account reale e darti da fare senza possedere MTProto?
->Messaggistica, cronologia delle chat e gestione dei partecipanti ai gruppi su un account utente connesso, con la sessione gestita automaticamente.Unipile
La maggior parte dei team arriva qui
Collega un account Telegram reale senza creare un client
Se il tuo progetto deve contattare per primo ma non ha bisogno di canali, chat segrete o chiamate, un account collegato tramite Unipile ti permette di farlo senza dover mantenere un'implementazione dell'API utente di Telegram.
Costruiscilo con Unipile

Telegram Bot API vs Telegram API - FAQ

Domande frequenti sulla scelta tra l'API Bot di Telegram e l'API utente di Telegram (MTProto).
Le Bot API sono un'interfaccia HTTP che pilota un account bot ed espone una superficie deliberatamente limitata. La Telegram API, chiamata anche Client API, utilizza il protocollo binario MTProto e pilota un account utente reale con l'insieme completo delle funzionalità. Sono tipi di account diversi, non due versioni della stessa cosa.
Chiedi a chi devi scrivere. Se i tuoi utenti ti scrivono per primi e l'identità di un bot è accettabile, usa la Bot API. Se devi raggiungere persone che non ti hanno contattato, o agire come una persona reale, ti serve l'accesso tramite account utente.
No. L'utente deve iniziare la conversazione per primo. Questo è l'unico limite che spinge la maggior parte dei prodotti fuori dalla Bot API, e nessun endpoint aggira questo problema.
No. L'API Bot richiede solo il token del bot fornito da BotFather. api_id e api_hash provengono da my.telegram.org e sono per l'API Client, con un solo api_id consentito per numero di telefono.
Difficile al punto che quasi nessuno lo scrive da zero. Gestisci la persistenza della sessione, l'autenticazione a due fattori, la riconnessione e un protocollo binario. La maggior parte dei team usa Telethon, Pyrogram, GramJS o TDLib, e gestisce comunque il ciclo di vita della sessione.
È un altro nome per la Client API, l'interfaccia MTProto che si autentica come un vero utente di Telegram anziché come un bot.
Sì. La connessione di un account esistente tramite la funzione Dispositivi di Telegram garantisce l'accesso all'account utente senza implementare MTProto. È così che Unipile collega gli account Telegram, tramite l'accesso con codice QR o un flusso di autenticazione ospitato.
Avete ancora domande? Il nostro team è qui per aiutarvi.
Parlare con un esperto
it_ITIT
en_USEN fr_FRFR es_ESES de_DEDE pt_BRBR nl_NLNL pl_PLPL tr_TRTR it_ITIT