Skip to main content
Il proxy dell’account Telegram fornisce interfacce MCP e REST indipendenti e persistenti per il tuo account Telegram personale. Ogni istanza serve un solo account; il contenitore non contiene AI e la sessione di accesso viene salvata nel volume persistente indipendente dell’istanza.
Questo non è un bot Telegram Bot API. Non utilizzarlo per messaggi spam, invii a freddo in massa o per aggirare le limitazioni di Telegram. Prima di inviare, modificare o eliminare contenuti a terzi, il tuo Agent deve ottenere una conferma esplicita.

​
Distribuzione e accesso

  1. Crea un proxy dell’account Telegram nella Console → Applicazioni, attiva un abbonamento e fai clic su distribuisci. Le risorse dell’istanza vengono configurate automaticamente dalla piattaforma.
  2. Quando l’istanza è pronta, fai clic su «Genera codice QR di accesso». Il codice QR è valido per un breve periodo e può essere rigenerato dopo la scadenza.
  3. In Telegram, apri Impostazioni → Dispositivi → Collega dispositivo desktop e scansiona il codice QR.
  4. Se lo stato diventa password_required, inserisci nella console la password della verifica in due passaggi di Telegram. La password viene inviata solo alla tua istanza tenant e non viene scritta nella configurazione della piattaforma.
  5. Dopo che lo stato diventa authenticated, la console mostra l’account corrente, l’indirizzo MCP e il token di accesso Bearer.
La sessione autorizzata viene archiviata nel volume persistente e viene riutilizzata durante i normali riavvii e aggiornamenti. «Esci dall’account» nella console chiama /api/auth/logout per revocare la sessione Telegram; «Distruggi istanza» elimina inoltre il carico di lavoro e il volume persistente.

​
Autenticazione e controllo dello stato

Oltre a /health e /readyz, le interfacce di accesso, REST e MCP richiedono tutte:
Il servizio accetta solo l’autenticazione tramite intestazione della richiesta e non supporta l’aggiunta del token all’URL. Proteggilo come proteggeresti la password del tuo account.
/health indica solo che il processo HTTP è attivo:
/readyz indica se la connessione MTProto è disponibile. Quando è connesso, restituisce HTTP 200, anche se l’account sta ancora scansionando il codice o attendendo la verifica in due passaggi:
Quando la connessione viene interrotta, il probe diretto di Kubernetes sul Pod restituisce HTTP 503 e l’istanza si riconnette automaticamente in background. In questo momento il Pod viene temporaneamente rimosso dal Service pubblico, pertanto non è garantito che sia possibile leggere il JSON diagnostico tramite il dominio dell’istanza; attendi nella console che il Deployment torni Ready. I valori comuni di login_state includono login_required, waiting_scan, password_required, authenticated; prima di eseguire operazioni sui messaggi dell’account è comunque necessario raggiungere authenticated.

​
Connessione di un client MCP

​
Claude Code

​
Client come Cursor che supportano intestazioni di richiesta statiche

Configura l’indirizzo Streamable HTTP in base alla documentazione corrente del client e aggiungi l’intestazione della richiesta Authorization. Ad esempio, i client che supportano la seguente struttura possono utilizzare:
Questo non è un formato di configurazione universale per tutti i client MCP. I connettori remoti di Claude Desktop / Claude.ai vengono stabiliti dal cloud e non leggono alcuna intestazione di richiesta HTTP in claude_desktop_config.json locale; attualmente, se hai bisogno di un’intestazione Bearer statica, utilizza Claude Code o un client che supporti esplicitamente questa funzionalità.

​
Strumenti MCP

target può essere l’ID della conversazione, il nome utente o il nome della conversazione esatto; se il nome è ambiguo, utilizza preferibilmente l’ID o il nome utente.

​
API REST

Tutte le risposte riuscite utilizzano {"data": ...}, mentre le risposte di errore utilizzano {"error": "..."}.

​
Esempi

​
Interfacce complete

​
Domande frequenti

  • 401：Token Bearer mancante o errato. Verifica che il token sia inserito nell’header della richiesta, non nei parametri di query URL.
  • 503：Token di accesso al proxy non configurato, oppure il client Telegram non è ancora pronto. Controlla prima /readyz; se il token di accesso al proxy non è configurato, anche le interfacce protette restituiranno 503.
  • 400：Parametro o JSON non valido; la ricerca deve fornire q, limit deve essere un numero intero maggiore o uguale a 1.
  • 403 / 404：L’account corrente non dispone dell’autorizzazione, oppure l’ID target / messaggio non esiste.
  • 429：È stato attivato il limite di frequenza di Telegram. Leggi retry_after e attendi, non riprovare in modo concorrente.
  • Il codice QR rimane sempre incompleto：Rigenera il codice QR e verifica di utilizzare l’ingresso di scansione Telegram «Collega dispositivo desktop».
  • Dopo il riavvio viene richiesto di effettuare nuovamente l’accesso：Verifica che il volume persistente dell’istanza funzioni correttamente; dopo l’uscita volontaria, la revoca della sessione nell’elenco dei dispositivi Telegram o la scadenza della sessione, è necessario eseguire nuovamente la scansione.

​
Ambito di verifica

Il codice sorgente e i test automatizzati coprono lo stato di accesso, il fail-close Bearer, la convalida dei parametri REST, la mappatura degli errori e l’implementazione della persistenza della sessione. L’utilizzo in produzione dovrebbe comunque prima completare smoke in sola lettura e di creazione/modifica/eliminazione dei messaggi su target=me (Messaggi salvati), prima di consentire all’Agent di operare su conversazioni di terze parti.