Oppsett av Telegram bot webhook: komplett guide for utviklere

Oppsett av Telegram bot webhook kobler serveren din til Telegrams oppdateringsstrøm slik at meldinger kommer i sanntid i stedet for i en polling-sløyfe. Hvis du bygger en tilpasset bot med Bot API, er webhooks standard produksjonsvei: Telegram POSTer hver oppdatering til ditt HTTPS-endepunkt, og koden din svarer.

Denne guiden går gjennom forutsetninger, registrering, et fungerende eksempel på en handler, verifisering, feilsøking, og når en administrert plattform som TeleClaw gir mer mening enn selv-hosting.

Viktige punkter

• Webhooks og long polling utelukker hverandre. Å sette en webhook deaktiverer getUpdates til du fjerner den.
• HTTPS er obligatorisk. Endepunktet ditt trenger TLS 1.2+, et matchende sertifikat, og port 443, 80, 88, eller 8443.
• Registrer med setWebhook, verifiser med getWebhookInfo. Sjekk last_error_message når oppdateringer slutter å flyte.
• Bruk secret_token for å bekrefte at forespørsler kommer fra Telegram, ikke tilfeldige skannere som treffer din URL.
• No-code alternativ: TeleClaw håndterer hosting og levering slik at du hopper over serverlaget helt.

Webhooks vs long polling: hvilken skal du velge

Telegram tilbyr to måter å motta oppdateringer på. Ifølge Bots FAQ velger du én metode per bot. Du kan ikke kjøre begge samtidig.

Long polling er den raskeste måten å prototype på. Boten din kaller getUpdates i en sløyfe, behandler hver batch, og flytter offset. Ingen domene, ingen sertifikat, ingen åpen port.

Webhooks snur modellen. Telegram sender en HTTPS POST til din URL når noen sender melding til boten. Det fjerner inaktive polling-forespørsler og kutter reaksjonstiden, noe som er viktig for støtteboter, betalingsflyter og gruppemoderering i stor skala.

Hvis du fortsatt registrerer boten selv, start med vår guide til å lage en Telegram bot for å få et token fra BotFather før du fortsetter her.

Forutsetninger for oppsett av Telegram bot webhook

Før du kaller setWebhook, bekreft at infrastrukturen din oppfyller Telegrams krav fra den offisielle webhook-guiden:

• Bot-token fra @BotFather (se guiden for å lage bot lenket ovenfor).
• Offentlig domene med et gyldig TLS-sertifikat. Selvsignerte sertifikater fungerer bare hvis du laster opp den offentlige nøkkelen via certificate-parameteren.
• Støttet port på serveren din: 443 (standard), 80, 88, eller 8443. Andre porter blir avvist.
• Sertifikat CN eller SAN må samsvare med domenet i din webhook-URL. Wildcard-sertifikater fungerer kanskje ikke. Omdirigeringer støttes ikke.
• Innkommende POST-tilgang fra Telegram-subnett 149.154.160.0/20 og 91.108.4.0/22.

For lokal utvikling, eksponer localhost gjennom en tunnel (ngrok, Cloudflare Tunnel, eller lignende) som gir deg en offentlig HTTPS-URL. Test at tunnelen returnerer HTTP 200 for POST-forespørsler før du registrerer webhooken.

Trinn 1: Bygg ditt webhook-endepunkt

Serveren din trenger en rute som aksepterer POST-forespørsler, parser JSON Update-objektet, og returnerer HTTP 200 raskt. Treg håndtering fører til at Telegram prøver på nytt og til slutt rapporterer feil i getWebhookInfo.

Minimalt Node.js-eksempel med Express:

import express from 'express';

const app = express();
app.use(express.json());

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // Process update.message, update.callback_query, etc.
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

Python med Flask følger samme mønster: les JSON fra request, valider hemmelighetsheaderen hvis konfigurert, behandle oppdateringen, returner 200.

Svar raskt. Tungt arbeid (database-skriving, AI API-kall) bør gå til en bakgrunnskø. Telegram forventer en rask bekreftelse. Du kan også svare inline ved å returnere en JSON-kropp med et method-felt i stedet for å foreta et separat API-kall, som beskrevet i Bot API webhook-notatene.

Trinn 2: Telegram bot konfigurer webhook med setWebhook

Når endepunktet ditt er live, registrer det med Bot API. Erstatt <TOKEN> og URL-en med dine verdier.

Bruker curl:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

Parameterreferanse:

• url (påkrevd): Ditt HTTPS-endepunkt. Bruk en tom streng for å fjerne webhooken.
• secret_token (valgfritt): 1-256 tegn (A-Z, a-z, 0-9, _, -). Telegram sender det i X-Telegram-Bot-Api-Secret-Token-headeren.
• max_connections (valgfritt): 1-100 samtidige tilkoblinger. Standard er 40.
• allowed_updates (valgfritt): Begrens hvilke oppdateringstyper du mottar. Reduserer nyttelaststørrelsen hvis du bare håndterer meldinger.
• drop_pending_updates (valgfritt): Sett true for å forkaste køede oppdateringer når du bytter webhooks.
• certificate (valgfritt): Last opp din offentlige nøkkelfil for selvsignerte sertifikater.

Et vellykket svar ser ut som {"ok":true,"result":true,"description":"Webhook was set"}.

Trinn 3: Verifiser med getWebhookInfo

Bekreft alltid registreringen umiddelbart. Dette er ditt første feilsøkingsverktøy når oppdateringer slutter å komme.

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

Eksempel på svar:

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

Se på disse feltene:

• url: Tom betyr at ingen webhook er aktiv (boten er på long polling).
• pending_update_count: Køede oppdateringer som venter på levering. Et stigende tall signaliserer leveringsfeil.
• last_error_date og last_error_message: Den siste feilårsaken. Fiks årsaken, så prøver Telegram automatisk på nytt.
• ip_address: Hvilken Telegram IP som for øyeblikket treffer endepunktet ditt.

Send en testmelding til boten din fra en ekte Telegram-konto. Hvis pending_update_count forblir null og serverloggene dine viser POST, fungerer oppsettet av Telegram bot webhook.

Telegram bot webhook eksempel: håndtering av forespørsel om å bli med

Boter for forespørsel om å bli med (Guardian-stil opptaksprosesser) trenger oppdateringstypen chat_join_request. Vår Guardian bot-guide dekker produktsiden. Her er webhook-koblingen.

Registrer med forespørsler om å bli med aktivert:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

Håndteringslogikk (pseudokode):

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // Kjør screeninglogikk, og godkjenn eller avvis deretter via Bot API
 await approveChatJoinRequest(chat.id, from.id);
}

Telegram leverer forespørsler om å bli med som push-oppdateringer, så webhooks er en naturlig passform for opptaksboter som må svare før forespørselen utløper.

Telegram bot fjern webhook og bytt tilbake til polling

Trenger du å feilsøke lokalt med getUpdates? Fjern webhooken først.

Alternativ A med deleteWebhook:

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

Alternativ B med setWebhook og tom URL:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

Begge metodene aktiverer long polling på nytt. Hvis du hopper over dette trinnet, returnerer getUpdates ingenting fordi webhooken fortsatt er registrert til din produksjons-URL.

Feilsøking av vanlige webhook-feil

Når getWebhookInfo viser feil, match meldingen med en løsning:

Kjør getWebhookInfo på en tidsplan i produksjon. Å fange last_error_message tidlig forhindrer timer med stille meldingstap.

Hopp over serveren: administrerte boter med TeleClaw

Ikke alle boter trenger tilpasset webhook-infrastruktur. Hvis målet ditt er en AI-assistent for en gruppe eller forretningskanal, er hosting og oppdateringslevering løste problemer.

TeleClaw kobler din BotFather-token til en administrert kjøretid drevet av OpenClaw. Du konfigurerer personlighet, kunnskapsbase og modereringsregler i dashbordet. Plattformen håndterer HTTPS-endepunkter, skalering og AI-modellruting. Legg til @claw som gruppeadmin og gå live uten å skrive en webhook-handler.

Utforsk hva en administrert bot kan gjøre på TeleClaw-funksjonssiden. For en fullstendig no-code gjennomgang, se vår Telegram chatbot uten kode-guide.

Tilpassede webhooks gir fortsatt mening når du trenger full kontroll: proprietære backends, regulert datalagring, eller ikke-standard oppdateringsbehandling. For alt annet hoper driftskostnadene for sertifikathåndtering, overvåking og gjenforsøk seg raskt opp.

Konklusjon

Oppsett av Telegram bot webhook koker ned til fire trinn: distribuer et HTTPS-endepunkt, kall setWebhook, verifiser med getWebhookInfo, og overvåk for feil. Bruk secret_token for forespørselsvalidering, begrens allowed_updates til det du behandler, og hold håndtererne raske.

Utviklere som ønsker produksjons-push-levering uten å kjøre servere kan bruke TeleClaw i stedet. Lim inn tokenet ditt, konfigurer AI-atferd, og fokuser på hva boten sier i stedet for hvordan oppdateringer kommer.

Klar til å lansere en AI-bot uten å administrere webhooks? Legg til @claw i Telegram-gruppen din →