Telegram access token uitgelegd: bottoken, API ID, API hash en session string

Veel mensen zoeken naar een "Telegram access token", alsof Telegram één universele sleutel uitgeeft. Dat doet het niet. Telegram heeft meerdere authenticatiesystemen, en welke gegevens je nodig hebt, hangt af van wat je software doet. Bestuurt die een bot? Autoriseert die een persoonlijk account? Logt die een gebruiker in op een website? Of maakt die opnieuw verbinding met een client die al geautoriseerd is?

Dat onderscheid is belangrijk, want elk soort gegevens geeft andere bevoegdheden. Een bottoken bestuurt één bot. Een API ID en API hash identificeren een ontwikkelaarsapplicatie. Een inlogcode bewijst tijdelijk toegang tot een telefoonnummer. Een session string of sessiebestand kan een voltooide autorisatie van een persoonlijk account bewaren en kan dus toegang tot het account geven zonder nieuwe inlogprompt. Wie deze waarden als uitwisselbaar behandelt, maakt een veelvoorkomende implementatiefout en loopt een serieus beveiligingsrisico.

Deze gids legt uit wat elk gegeven doet, waar het vandaan komt en hoe je er veilig mee omgaat. Je leest ook waarom een Telegram CRM of MCP-koppeling voor persoonlijke accounts niet hetzelfde is als een integratie met de Bot API.

Vraagt een tutorial om een "Telegram token"? Stop dan en zoek eerst uit welke rij bedoeld wordt, voordat je iets kopieert.

Een Telegram-bottoken authenticeert een bot bij de Bot API. De officiële bottutorial van Telegram laat ontwikkelaars een bot aanmaken via @BotFather, meestal met het commando /newbot. BotFather geeft een token terug dat de backend gebruikt om methodes als getMe, sendMessage of setWebhook aan te roepen.

Een bottoken ziet er meestal uit als een numerieke bot-ID, gevolgd door een dubbele punt en een lang geheim. Plak nooit een echt token in documentatie, screenshots, chatberichten, issuetrackers, JavaScript aan de clientkant of een openbare repository. Telegram raadt uitdrukkelijk aan het token als een wachtwoord te behandelen, want iedereen die het heeft, kan de bot besturen.

Bottokens hebben een belangrijke beperking: ze authenticeren de identiteit van de bot, niet je persoonlijke Telegram-identiteit. Bots kunnen niet zomaar iemands bestaande privé-inbox lezen. De botdocumentatie van Telegram legt ook uit dat bots geen gesprek met een gebruiker kunnen beginnen. Een gebruiker moet de bot eerst zelf benaderen of aan een groep toevoegen. In groepen kunnen privacy-instellingen bovendien beperken welke berichten de bot ontvangt.

Kies een bottoken als je een botervaring bouwt: commando's, meldingen, menu's, intake voor support, een Mini App of een geautomatiseerde workflow waarin gebruikers bewust met een bot werken.

Clients voor persoonlijke accounts gebruiken de MTProto API van Telegram, in plaats van alleen de HTTP Bot API. Elke Telegram-app van derden is zo'n client. Daarom is het kiezen van een Telegram-client voor een werkaccount een beveiligingsbeslissing. Voordat een applicatie een Telegram-gebruiker kan autoriseren, heeft de ontwikkelaar een API ID en API hash nodig.

De officiële instructies voor het registreren van een applicatie beschrijven het proces:

1. Gebruik een actief telefoonnummer dat bij Telegram geregistreerd is.
2. Log in op my.telegram.org.
3. Open API development tools (tools voor API-ontwikkeling).
4. Registreer de applicatie.
5. Bewaar de api_id en api_hash die je krijgt op een veilige plek.

De API ID is een numerieke identificatie van de applicatie. De API hash is het bijbehorende geheim. Samen identificeren ze de software die om autorisatie vraagt. Ze loggen die software niet zelf in op elk Telegram-account. Daarvoor is nog steeds een autorisatieflow van de gebruiker nodig.

Kopieer geen API-gegevens uit een willekeurig GitHub-project of voorbeeldapplicatie. Telegram waarschuwt dat de voorbeeld-API ID in zijn open-sourcecode beperkt is en niet geschikt voor applicaties die je aan gebruikers uitbrengt. Een integratie in productie hoort gegevens te gebruiken die geregistreerd zijn op naam van de organisatie die haar beheert, en moet voldoen aan de API-voorwaarden van Telegram.

Autoriseert een MTProto-client een persoonlijk account, dan stuurt Telegram meestal een tijdelijke inlogcode via een bestaande Telegram-sessie of een ander ondersteund kanaal. Staat tweestapsverificatie aan op het account, dan vraagt Telegram ook om het extra wachtwoord van het account.

Geen van beide waarden is een API-gegeven dat een ontwikkelaar permanent hoort op te slaan. De code is een tijdelijk bewijs dat de persoon die het account beheert de login goedkeurt. Het wachtwoord voor tweestapsverificatie is het wachtwoord van de accounteigenaar. Een legitiem autorisatiescherm legt uit waarom de waarde nodig is, verstuurt die veilig en legt die niet vast in logs of analytics.

Stuur een Telegram-inlogcode nooit naar iemand die zegt van support te zijn. Plak er nooit een in een gesprek met een bot. Wordt er buiten een inlogflow om een inlogcode gevraagd, dan is dat een sterk signaal dat iemand je account wil overnemen.

Na een geslaagde autorisatie bewaren MTProto-bibliotheken meestal een sessie. Afhankelijk van de bibliotheek staat die sessie in een lokaal databasebestand, een versleuteld record of een overdraagbare string.

Dankzij de sessie hoeven gebruikers niet bij elke herstart van de applicatie een nieuwe inlogcode in te voeren. Juist dat gemak maakt haar zeer gevoelig. Een geldige sessie kan een apparaat voorstellen dat al geautoriseerd is. Lekt ze uit, dan kan iemand anders via het account handelen tot de sessie wordt ingetrokken.

Houd je aan deze regels:

• Commit sessies nooit naar Git.
• Neem ze nooit op in browsercode of analytics van mobiele apps.
• Versleutel ze in opslag met een beheerde sleutel, niet met een hardgecodeerde sleutel naast de versleutelde tekst.
• Beperk toegang in productie tot de kleinst mogelijke servicerol.
• Haal ze weg uit logs en foutrapporten.
• Bied een duidelijke manier om het account los te koppelen en de opgeslagen sessie te verwijderen.
• Trek een uitgelekte sessie in via het scherm Settings → Devices (Instellingen, Apparaten) van Telegram en vervang de gerelateerde geheimen.

Een session string is geen veiligere versie van een bottoken. Het is een ander soort gegeven, met mogelijk veel ruimere toegang.

Telegram ondersteunt ook inloggen op websites en applicaties via Telegram Login, de "Telegram login API" die de meeste tutorials bedoelen, inclusief een OpenID Connect-flow. Die flow authenticeert een Telegram-gebruiker bij een andere applicatie en geeft ondertekende identiteitsgegevens of tokens met een beperkte scope terug. Dat geeft niet automatisch toestemming om de persoonlijke Telegram-inbox van de gebruiker te lezen.

Gebruik Telegram Login als het doel is "log in op mijn dienst met Telegram". Gebruik de Bot API voor een bot. Gebruik een geautoriseerde MTProto-client als het product echt functies van een persoonlijk account nodig heeft en een helder model voor toestemming en beveiliging heeft.

MCP beschrijft hoe een AI-client tools en acties opvraagt bij een server. Het vervangt de authenticatie van Telegram niet. Een Telegram MCP-server heeft nog steeds een geautoriseerde Telegram-laag achter zich nodig.

Entergram koppelt bijvoorbeeld persoonlijke Telegram-accounts aan een workspace via een autorisatieflow die de gebruiker zelf goedkeurt. De gehoste Telegram MCP-server stelt daarna afgebakende CRM- en berichtentools beschikbaar aan een goedgekeurde MCP-client. De AI-client krijgt toegang tot tools. Hij hoort geen ruwe Telegram-inlogcodes, API hashes of herbruikbare accountsessies te krijgen.

Deze scheiding is de veiligere architectuur:

1. Telegram-gegevens blijven binnen de dienst die verantwoordelijk is voor de Telegram-autorisatie.
2. De MCP-server stelt alleen nauw omschreven handelingen beschikbaar.
3. OAuth en workspace-rechten bepalen welke persoon of AI-client die handelingen mag aanroepen.
4. Auditlogs leggen zakelijke handelingen vast zonder authenticatiegeheimen op te slaan.
5. Je kunt de MCP-client uitschakelen zonder dat de gebruiker elk onderliggend Telegram-gegeven hoeft prijs te geven of te vervangen.

Lees Telegram MCP versus de Bot API voor de verschillen in mogelijkheden.

Beantwoord deze vragen voordat je een Telegram-integratie uitrolt:

• Handelt de integratie als bot of als persoonlijk account?
• Welke chats en handelingen heeft ze echt nodig?
• Kan de gebruiker privégesprekken of accounts uitsluiten?
• Zijn schrijfacties gescheiden van acties die alleen lezen?

• Staan bottokens, API hashes en sessies alleen op vertrouwde servers?
• Zijn geheimen versleuteld in opslag en beschermd tijdens verzending?
• Blijven productiegegevens buiten versiebeheer en previewdeployments?
• Zijn logs, tracingsystemen en supporttools zo ingesteld dat ze geheimen wegfilteren?

• Heeft elk gekoppeld account een herkenbare eigenaar?
• Kan een beheerder één account loskoppelen zonder de andere te raken?
• Kun je de toegang van één AI-client of medewerker apart intrekken?
• Worden bevoorrechte handelingen vastgelegd met uitvoerder, tijd, account en resultaat?

• Is er een vastgelegde procedure om een bottoken te vervangen?
• Kan het team een gestolen sessie snel ongeldig maken?
• Waarschuwt de dienst bij ongebruikelijke inloglocaties of grote aantallen handelingen?
• Zijn back-ups versleuteld en vallen ze onder hetzelfde verwijderbeleid?

Elk gegeven een token noemen. Daardoor zetten engineers de verkeerde waarde in het verkeerde veld en worden beveiligingsreviews onduidelijk. Geef configuratievariabelen precieze namen: TELEGRAM_BOT_TOKEN, TELEGRAM_API_ID en TELEGRAM_API_HASH zijn duidelijker dan TELEGRAM_TOKEN.

Een bottoken in frontendcode zetten. Alles wat naar een browser gaat, moet je als openbaar beschouwen. Laat Bot API-aanroepen via een beschermde backend lopen.

Aannemen dat API ID en API hash gelijkstaan aan toegang tot een account. Ze identificeren de applicatie. De gebruiker moet het account nog steeds autoriseren.

Een sessie behandelen als onschuldige cache. Een sessie is authenticatiemateriaal. Bescherm haar als inloggegevens en zorg dat je haar kunt intrekken.

Meer toegang verzamelen dan de workflow nodig heeft. Een meldingenbot heeft geen sessie van een persoonlijk account nodig. Een rapportageworkflow heeft misschien geen recht nodig om berichten te versturen. Begin met het smalste ontwerp dat werkt.

Er is dus geen enkel access token dat Telegram voor alles uitgeeft. Wil je een Telegram-bot bouwen, maak die dan aan met BotFather en gebruik het bottoken op je backend. Ontwikkel je een geautoriseerde Telegram-client voor persoonlijke accounts, registreer dan je eigen API ID en API hash, rond de autorisatieflow van Telegram voor gebruikers af en bescherm de sessie die daaruit komt. Heb je alleen inloggen nodig, gebruik dan Telegram Login en vraag geen toegang tot de inbox.

Voor teams die AI-tools met goedgekeurde persoonlijke Telegram-accounts willen laten werken, voorkomt een Telegram MCP-server met rechtenbeheer dat ruwe Telegram-gegevens in elke AI-client terechtkomen. Welke route je ook kiest: houd authenticatiegeheimen buiten prompts, repositories, browsercode en screenshots, en bouw de mogelijkheid tot intrekken vanaf de eerste dag in je ontwerp.