Build a Telegram Bot for Free on Cloudflare Workers, Step by Step

Create the bot

In Telegram, message BotFather, send /newbot, choose a name and a username. Copy the token it gives you.

Create a Worker project

Run npm create cloudflare@latest my-bot, choose a Hello World Worker in JavaScript, then cd my-bot.

Store the token as a secret

Run npx wrangler secret put BOT_TOKEN and paste the token. It is now available as env.BOT_TOKEN and never in your code.

Write the handler

In src/index.js:

export default {
  async fetch(request, env) {
    if (request.method !== 'POST') return new Response('ok');
    const update = await request.json();
    const msg = update.message;
    if (!msg || !msg.text) return new Response('ok');
    const reply = msg.text === '/start' ? 'Hello! Send me any text.' : `You said: ${msg.text}`;
    await fetch(`https://api.telegram.org/bot${env.BOT_TOKEN}/sendMessage`, {
      method: 'POST', headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ chat_id: msg.chat.id, text: reply })
    });
    return new Response('ok');
  }
}

Deploy

Run npx wrangler deploy. Copy the workers.dev URL it prints.

Set the webhook

Open in a browser (with your values): https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://<your-worker>.workers.dev. Telegram replies with "ok": true.

Test

Message your bot in Telegram. Send /start and a sentence; you should get replies within a second.

Add one real feature

For example, call a public API (weather, exchange rate, a quote) and format the result, or store user notes in Workers KV (free tier).

Protect the webhook

Set a secret token with setWebhook's secret_token parameter and check the X-Telegram-Bot-Api-Secret-Token header in the Worker, so only Telegram can call it.

Document

Add the commands, the deploy steps and the free-plan limits to your README.