Telegram Bot API handleiding: bouw je eerste bot

De snelste Telegram Bot API handleiding bestaat uit drie commando’s: haal een token op bij BotFather, roep getUpdates aan om berichten te lezen, en roep sendMessage aan om te antwoorden. Al het andere in botontwikkeling bouwt voort op deze cyclus. Deze gids neemt je mee door het hele traject, van je eerste cURL-verzoek tot een werkende bot met een webhook en een bibliotheek.

De Bot API is een HTTP-interface, wat betekent dat je deze kunt testen met curl voordat je ook maar één regel applicatiecode schrijft. Dat maakt het een van de vriendelijkere API’s om te leren. Als je een ontwikkelaar bent die vandaag nog een werkende bot wil, of een bouwer die code afweegt tegen een no-code platform zoals TeleClaw, dan ben je hier aan het juiste adres.

Aan het einde begrijp je hoe de API verzoeken authenticeert, hoe je berichten ontvangt en verzendt, het verschil tussen long polling en webhooks, en de rate limits die de meeste eerste bots in de problemen brengen.

Belangrijkste inzichten

• Een bot is gewoon een HTTP-client. Elke methode is een verzoek naar https://api.telegram.org/bot<TOKEN>/METHOD_NAME, dus cURL is voldoende om te beginnen.
• Drie kernmethoden zorgen ervoor dat je aan de slag kunt: getMe om de token te verifiëren, getUpdates om berichten te lezen, en sendMessage om te antwoorden.
• Long polling en webhooks sluiten elkaar uit. Gebruik polling voor lokaal testen, schakel over naar een webhook voor productie.
• De API is gratis, maar Telegram beperkt bulkverzending tot ongeveer 30 berichten per seconde naar verschillende gebruikers en één per seconde per chat.
• Een bibliotheek bespaart tijd zodra je bot verder gaat dan een script. Gebruik python-telegram-bot, aiogram of Telegraf.

Wat is de Telegram Bot API?

De Telegram Bot API is een HTTP-gebaseerde interface voor het verbinden van je code met Telegram via een bot. Volgens de ontwikkelaarsintroductie van Telegram zijn bots speciale accounts die geen telefoonnummer vereisen en dienen als een interface voor code die op je server draait.

Elk verzoek dat je doet, authenticeert met een bottoken in plaats van een gebruikersaccount. De token identificeert de bot, dus behandel het als een wachtwoord en commit het nooit naar een openbare repository. De documentatie van Telegram zegt het duidelijk: bewaar je token op een veilige plaats en deel het niet.

De API zelf is gratis. Telegram biedt de Bot API gratis aan sinds de lancering, zonder kosten per bericht en zonder limiet op het aantal bots dat je kunt maken. Daarom draaien er zoveel communitytools, ondersteuningsassistenten en automatiseringen op. Als je nieuw bent op het platform, behandelt onze gids over hoe je een Telegram-bot maakt de accountconfiguratie in meer detail.

Stap 1: Haal een bottoken op bij BotFather

Open Telegram en zoek naar @BotFather, de officiële bot voor het maken en beheren van andere bots. Start een chat en stuur het commando /newbot.

BotFather vraagt vervolgens twee dingen achter elkaar:

1. Een weergavenaam voor je bot, zoals “Mijn Eerste API Bot”.
2. Een gebruikersnaam die eindigt op bot, zoals eerste_api_demo_bot.

Wanneer je klaar bent, retourneert BotFather een API-token dat eruitziet als 123456789:AAExampleTokenStringHere. Deze token is de enige referentie die je nodig hebt voor de rest van deze handleiding.

Let op: Iedereen met jouw token beheert jouw bot. Bewaar het in een omgevingsvariabele, niet in de broncode. Als het uitlekt, stuur dan /revoke naar BotFather en vraag een nieuwe aan.

Stap 2: Roep je eerste Bot API-methode aan

Voordat je een programma schrijft, controleer je of de token werkt. De getMe-methode retourneert basisinformatie over je bot en is de standaard gezondheidscheck. Vervang <YOUR_TOKEN> door de waarde van BotFather.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

Een succesvol antwoord is JSON met "ok": true en de ID, naam en gebruikersnaam van je bot. Als je "ok": false ziet, is de token verkeerd of bevat deze een typefout.

Dat ene verzoek is het hele patroon. Elke Telegram Bot API-methode volgt dezelfde vorm: een HTTPS-aanroep naar https://api.telegram.org/bot<TOKEN>/METHOD_NAME, met parameters in de query string of POST-body, en een JSON-object als antwoord. De volledige lijst staat in de Bot API-referentie, die elke methode en elk object documenteert dat je ooit nodig zult hebben.

Stap 3: Berichten ontvangen en verzenden

Maak de bot nu nuttig. Er is één regel die beginners verrast: een bot kan geen gesprek beginnen. De gebruiker moet de bot eerst een bericht sturen. Dus open je bot in Telegram en stuur hem een willekeurige tekst, zoals “hallo”.

Lees vervolgens dat bericht met getUpdates, dat inkomende updates ophaalt met behulp van long polling en een array van update-objecten retourneert.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

Zoek in het antwoord naar message.chat.id. Die chat_id is het adres waarnaar je antwoordt. Kopieer het en roep vervolgens sendMessage aan:

curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
 -d chat_id=<CHAT_ID> \
 -d text="Hallo vanuit mijn eerste bot"

Je bot antwoordt in de chat. Die heen-en-weer-beweging, lezen met getUpdates en antwoorden met sendMessage, is de kernlus achter de meeste Telegram-bots. De text-parameter accepteert tot 4096 tekens per bericht, dus lange antwoorden moeten worden opgesplitst.

Twee details om te onthouden wanneer je dit Telegram Bot API-voorbeeld opschaalt naar echte code:

• Bereken de offset opnieuw. Geef de update_id van de laatste update plus één door als de offset-parameter bij je volgende getUpdates-aanroep, anders blijft Telegram dezelfde updates retourneren.
• Eén methode tegelijk. getUpdates stopt met werken zodra je een webhook registreert, wat het onderwerp is van de volgende stap.

Stap 4: Kies long polling of een webhook

Telegram biedt twee manieren om updates te ontvangen, en je kunt er maar één per bot tegelijk gebruiken.

• Long polling betekent dat je code herhaaldelijk getUpdates aanroept. Dit is de gemakkelijkste weg voor leren en lokale ontwikkeling, omdat het geen openbare URL nodig heeft, alleen een proces dat blijft draaien.
• Webhooks betekenen dat Telegram elke update naar je HTTPS-eindpunt pusht als een POST-verzoek op het moment dat het gebeurt. Dit is de productiestandaard: lagere latentie, geen inactieve polling, en het schaalt beter onder constante verkeer.

Om over te schakelen naar een webhook, registreer je eenmalig je openbare HTTPS-URL:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://yourdomain.com/webhook"

Je eindpunt heeft een geldig TLS-certificaat nodig en moet snel HTTP 200 retourneren. Als updates niet meer aankomen, is de eerste stap altijd om de fout te inspecteren. Voor de volledige registratie-, verificatie- en probleemoplossingsstroom, zie onze Telegram bot webhook setup guide. De korte versie: begin met polling terwijl je bouwt, schakel over naar een webhook voordat je lanceert.

Stap 5: Verpak de API in een bibliotheek

Ruwe cURL is geweldig om te leren, maar productie-bots gebruiken een bibliotheek. Een bibliotheek handelt de API-aanroepen, update-parsing, retries en gespreksstatus af, zodat je alleen je botspecifieke logica schrijft. Telegram vermeldt communitybibliotheken voor bijna elke taal op zijn Bot API-voorbeeldenpagina.

Kies op basis van de taal die je al kent:

• Python: python-telegram-bot is puur Python, volledig asynchroon en ondersteunt Python 3.10 en hoger. aiogram en pyTelegramBotAPI zijn populaire alternatieven.
• Node.js: Telegraf is volwassen en TypeScript-vriendelijk. node-telegram-bot-api is een lang bestaande optie.

Hier is dezelfde echobot in Python, het meest voorkomende startpunt voor een Telegram Bot API Python-handleiding:

from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes

TOKEN = "YOUR_TOKEN"

async def echo(update: Update, context: ContextTypes. DEFAULT_TYPE):
 await update.message.reply_text(update.message.text)

app = Application.builder().token(TOKEN).build()
app.add_handler(MessageHandler(filters. TEXT & ~filters. COMMAND, echo))
app.run_polling()

En het Node.js-equivalent met Telegraf:

import { Telegraf } from 'telegraf'

const bot = new Telegraf(process.env. BOT_TOKEN)
bot.on('text', (ctx) => ctx.reply(ctx.message.text))
bot.launch()

Beide doen hetzelfde werk als de cURL-lus uit stap 3, maar in een paar regels en met de rommelige delen voor je afgehandeld. Maria, een backend-ontwikkelaar die een supportbot prototypeerde, stapte in één middag over van cURL-tests naar python-telegram-bot en had dezelfde dag command handlers en inline-knoppen werkend. De API-concepten werden direct overgenomen omdat de bibliotheek een dunne wrapper is over dezelfde HTTP-methoden.

Rate limits en quota om te kennen

De API is gratis, maar niet onbeperkt. De Bots FAQ van Telegram geeft richtlijnen om te voorkomen dat je bot wordt afgeremd.

• Eén bericht per seconde per chat. Vermijd in een enkel gesprek sneller te verzenden dan dat.
• Ongeveer 30 berichten per seconde in totaal bij verzending naar veel verschillende gebruikers. Ga je hier overheen, dan ontvang je HTTP 429 “Too Many Requests” antwoorden.
• Ongeveer 20 berichten per minuut naar dezelfde groep.

Wanneer een uitzending echt meer nodig heeft, kun je ‘Paid Broadcasts’ inschakelen in @BotFather, wat het plafond verhoogt naar 1000 berichten per seconde. Berichten boven de gratis 30 per seconde kosten 0,1 Telegram Stars per stuk. De meeste bots hebben dit nooit nodig, maar het is goed om te weten dat de limiet bestaat voordat je een notificatiefunctie ontwerpt.

Respecteer een 429 door de retry_after-waarde die Telegram retourneert te lezen en voor dat aantal seconden te pauzeren. Een bibliotheek regelt dit voor je, wat nog een reden is om van ruwe verzoeken af te stappen zodra je verkeer serieus wordt.

Sla de code over: AI-bots zonder server

Niet elk project heeft een aangepaste codebase nodig. Als je doel een AI-assistent in een Telegram-groep is, is de Bot API misschien een onderdeel dat je niet zelf wilt onderhouden, vooral de hosting, HTTPS en webhook-laag.

TeleClaw is een no-code platform dat de bot voor je draait en Claude AI direct koppelt. Je voegt @claw toe aan je groep, plakt je BotFather-token in het dashboard en configureert gedrag zonder setWebhook of rate-limit afhandeling aan te raken. Tomas, die een crypto-community met 4.000 leden beheert, verving een half afgemaakte aangepaste bot door TeleClaw en had dezelfde avond AI-moderatie en FAQ-antwoorden live.

Het is dezelfde Bot API die eronder ligt. Je kiest of je de serverlaag zelf beheert of dit door een platform laat doen. Ontdek wat dat allemaal omvat op de TeleClaw-functiespagina, en vergelijk opties in onze beste Telegram-bots roundup. Voor een pure dashboard-build, zie onze no-code Telegram chatbot gids.

Conclusie

Je hebt nu een werkend mentaal model van de Telegram Bot API: een token van BotFather, HTTP-methoden zoals getMe, getUpdates en sendMessage, een keuze tussen long polling en webhooks, en een bibliotheek om alles te omvatten zodra je bot groeit. De API is gratis, goed gedocumenteerd en toegankelijk genoeg om binnen enkele minuten met cURL te testen.

De snelste volgende stap is de kleinste. Open @BotFather, voer /newbot uit en stuur je eerste getMe-verzoek om de token te bevestigen. Vanaf daar kun je bouwen in Python of Node, of de server helemaal overslaan. Om een AI-gestuurde bot in minuten in plaats van dagen te lanceren, voeg je @claw toe aan je groep en configureer je deze in het TeleClaw-dashboard.