Telegram Bot API tutorial: build your first bot

The fastest Telegram Bot API tutorial is three commands: get a token from BotFather, call getUpdates to read messages, and call sendMessage to reply. Everything else in bot development builds on that loop. This guide walks through the full path, from your first cURL request to a running bot with a webhook and a library.

The Bot API is an HTTP interface, which means you can test it with curl before you write a single line of application code. That makes it one of the friendlier APIs to learn. If you are a developer who wants a working bot today, or a builder weighing code against a no-code platform like TeleClaw, you are in the right place.

By the end you will understand how the API authenticates requests, how to receive and send messages, the difference between long polling and webhooks, and the rate limits that trip up most first bots.

Key takeaways

• A bot is just an HTTP client. Every method is a request to https://api.telegram.org/bot<TOKEN>/METHOD_NAME, so cURL is enough to start.
• Three core methods get you running: getMe to verify the token, getUpdates to read messages, and sendMessage to reply.
• Long polling and webhooks are mutually exclusive. Poll for local testing, switch to a webhook for production.
• The API is free, but Telegram caps bulk sending at roughly 30 messages per second to different users and one per second per chat.
• A library saves time once your bot grows past a script. Use python-telegram-bot, aiogram, or Telegraf.

What is the Telegram Bot API?

The Telegram Bot API is an HTTP-based interface for connecting your code to Telegram through a bot. According to Telegram’s developer introduction, bots are special accounts that do not require a phone number and serve as an interface for code running on your server.

Every request you make authenticates with a bot token rather than a user account. The token identifies the bot, so you treat it like a password and never commit it to a public repository. Telegram’s docs say it plainly: save your token in a secure place and do not share it.

The API itself is free. Telegram has offered the Bot API free of charge since it launched, with no per-message fee and no cap on how many bots you create. That is why so many community tools, support assistants, and automations run on it. If you are new to the platform, our guide on how to create a Telegram bot covers the account setup side in more detail.

Step 1: Get a bot token from BotFather

Open Telegram and search for @BotFather, the official bot for creating and managing other bots. Start a chat and send the /newbot command.

BotFather then asks two things in order:

1. A display name for your bot, like “First API Bot”.
2. A username that ends in bot, like first_api_demo_bot.

When you finish, BotFather returns an API token that looks like 123456789:AAExampleTokenStringHere. This token is the only credential you need for the rest of this tutorial.

Heads up: Anyone with your token controls your bot. Keep it in an environment variable, not in source code. If it leaks, send /revoke to BotFather and get a fresh one.

Step 2: Call your first Bot API method

Before writing any program, confirm the token works. The getMe method returns basic information about your bot and is the standard health check. Replace <YOUR_TOKEN> with the value from BotFather.

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

A successful response is JSON with "ok": true and your bot’s id, name, and username. If you see "ok": false, the token is wrong or has a typo.

That single request is the whole pattern. Every Telegram Bot API method follows the same shape: an HTTPS call to https://api.telegram.org/bot<TOKEN>/METHOD_NAME, with parameters in the query string or POST body, and a JSON object in return. The full list lives in the Bot API reference, which documents every method and object you will ever need.

Step 3: Receive and send messages

Now make the bot useful. There is one rule that surprises beginners: a bot cannot start a conversation. The user has to message the bot first. So open your bot in Telegram and send it any text, like “hello”.

Next, read that message with getUpdates, which fetches incoming updates using long polling and returns an array of update objects.

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

In the response, find message.chat.id. That chat_id is the address you reply to. Copy it, then call sendMessage:

curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
 -d chat_id=<CHAT_ID> \
 -d text="Hello from my first bot"

Your bot replies in the chat. That round trip, read with getUpdates and respond with sendMessage, is the core loop behind most Telegram bots. The text parameter accepts up to 4096 characters per message, so long replies need to be split.

Two details to remember as you scale this telegram bot api example into real code:

• Recalculate the offset. Pass the last update’s update_id plus one as the offset parameter on your next getUpdates call, or Telegram keeps returning the same updates.
• One method at a time. getUpdates stops working the moment you register a webhook, which is the topic of the next step.

Step 4: Choose long polling or a webhook

Telegram offers two ways to receive updates, and you can only use one per bot at a time.

• Long polling means your code repeatedly calls getUpdates. It is the easiest path for learning and local development because it needs no public URL, just a process that keeps running.
• Webhooks mean Telegram pushes each update to your HTTPS endpoint as a POST request the instant it happens. This is the production standard: lower latency, no idle polling, and it scales better under steady traffic.

To switch to a webhook, register your public HTTPS URL once:

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

Your endpoint needs a valid TLS certificate and must return HTTP 200 quickly. If updates stop arriving, the first move is always to inspect the error. For the full registration, verification, and troubleshooting flow, see our Telegram bot webhook setup guide. The short version: start with polling while you build, move to a webhook before you launch.

Step 5: Wrap the API in a library

Raw cURL is great for learning, but production bots use a library. A library handles the API calls, update parsing, retries, and conversation state, so you write only your bot-specific logic. Telegram lists community libraries for nearly every language on its Bot API samples page.

Pick by the language you already know:

• Python: python-telegram-bot is pure Python, fully asynchronous, and supports Python 3.10 and up. aiogram and pyTelegramBotAPI are popular alternatives.
• Node.js: Telegraf is mature and TypeScript-friendly. node-telegram-bot-api is a long-standing option.

Here is the same echo bot in Python, the most common starting point for a telegram bot api python tutorial:

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()

And the Node.js equivalent with Telegraf:

import { Telegraf } from 'telegraf'

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

Both do the same job as the cURL loop from Step 3, but in a few lines and with the messy parts handled for you. Maria, a backend developer prototyping a support bot, moved from cURL tests to python-telegram-bot in an afternoon and had command handlers and inline buttons working the same day. The API concepts carried over directly because the library is a thin wrapper over the same HTTP methods.

Rate limits and quotas to know

The API is free, but it is not unlimited. Telegram’s Bots FAQ lists the guidance that keeps your bot from getting throttled.

• One message per second per chat. In a single conversation, avoid sending faster than that.
• About 30 messages per second total when sending to many different users. Go over and you start receiving HTTP 429 “Too Many Requests” responses.
• Roughly 20 messages per minute to the same group.

When a broadcast genuinely needs more, you can enable Paid Broadcasts in @BotFather, which raises the ceiling toward 1000 messages per second. Messages beyond the free 30 per second cost 0.1 Telegram Stars each. Most bots never need this, but it is good to know the limit exists before you design a notification feature.

Respect a 429 by reading the retry_after value Telegram returns and pausing for that many seconds. A library handles this for you, which is one more reason to graduate from raw requests once your traffic is real.

Skip the code: AI bots without a server

Not every project needs a custom codebase. If your goal is an AI assistant in a Telegram group, the Bot API is plumbing you may not want to maintain yourself, especially the hosting, HTTPS, and webhook layer.

TeleClaw is a no-code platform that runs the bot for you and connects Claude AI out of the box. You add @claw to your group, paste your BotFather token into the dashboard, and configure behavior without touching setWebhook or rate-limit handling. Tomas, who runs a 4,000-member crypto community, replaced a half-finished custom bot with TeleClaw and had AI moderation and FAQ answers live the same evening.

It is the same Bot API underneath. You are choosing whether to operate the server layer yourself or let a platform do it. Explore what that covers on the TeleClaw features page, and compare options in our best Telegram bots roundup. For a pure dashboard build, see our no-code Telegram chatbot guide.

Conclusion

You now have a working mental model of the Telegram Bot API: a token from BotFather, HTTP methods like getMe, getUpdates, and sendMessage, a choice between long polling and webhooks, and a library to wrap it all once your bot grows. The API is free, well-documented, and approachable enough to test with cURL in minutes.

The fastest next step is the smallest one. Open @BotFather, run /newbot, and send your first getMe request to confirm the token. From there you can build in Python or Node, or skip the server entirely. To launch an AI-powered bot in minutes instead of days, add @claw to your group and configure it in the TeleClaw dashboard.