How to Get a Telegram API Key and Build a Bot Integration

Telegram is one of the friendlier platforms to build on, but newcomers hit an early fork that quietly decides the shape of the whole project: there are two different credentials, obtained in two different places, for two different purposes. Grab the wrong one and you spend an afternoon fighting an API that was never meant for your use case. This guide clears that up first, then walks through getting your credential and turning it into a working bot integration, with the practical gotchas that the official docs tend to gloss over.

Introduction

Ask five developers how to get a Telegram API key and you will get answers that seem to contradict each other, because Telegram exposes two distinct access paths. One is the Bot API, which hands you a bot token from a chat with a bot called BotFather. The other is the MTProto client API, which gives you an api_id and api_hash from Telegram’s website and lets you build full client applications. They are not interchangeable, and choosing between them is the single most important decision before you write any code. This guide explains the fork, walks through obtaining each credential, and shows how to go from a token to a running integration. If you want a companion reference to follow along with, this step-by-step guide to getting a telegram api key covers the same ground in detail.

Two APIs, two credentials, two mental models

The Bot API is a friendly HTTP layer. You talk to it over ordinary HTTPS requests, you receive updates as JSON, and you never touch Telegram’s underlying protocol. It exists so that most people can build bots without learning anything low level. The credential is a bot token, a string like 123456789:ABC…, and it identifies a bot account, not a human user.

The MTProto client API is the lower-level path. It speaks Telegram’s own binary protocol, and it is what powers real Telegram client apps. Here the credential is a pair, api_id and api_hash, and it authenticates an application acting on behalf of a real user account rather than a bot. You reach for this when you need capabilities that bots simply do not have.

The rule of thumb: if you are building something that behaves like an automated participant, a notifier, a command responder, a chat assistant, use the Bot API. If you are building something that needs to act as a user, read arbitrary history, or do things bots are forbidden from, you are in MTProto territory, which is more powerful and considerably more involved.

Getting a bot token from BotFather

For the Bot API path, the “key” is a bot token, and you get it by talking to a bot. Open Telegram, search for BotFather, the official account for creating bots, and start a chat. Send the command to create a new bot, give it a display name, then a username that ends in “bot” and is globally unique. BotFather replies with your token. That single string is your credential and your secret at the same time, so treat it like a password: anyone holding it can fully control your bot. If it ever leaks, BotFather can revoke and reissue it.

While you are in that chat, it is worth setting a few things BotFather also controls: a description and about text, a profile picture, the list of commands so users see suggestions, and privacy mode. Privacy mode is a detail people miss. By default a bot in a group only receives messages that mention it or reply to it, not every message in the chat. If your bot needs to read all group messages, you have to turn privacy mode off through BotFather, and even then group admins can constrain it. Deciding this early saves confusion later when your bot seems to ignore messages it should see.

Getting api_id and api_hash from my.telegram.org

If your use case genuinely needs the client API, the credential comes from Telegram’s website rather than a chat. Sign in at my.telegram.org with your phone number, open the API development tools section, and register a new application by giving it a name and a short identifier. Telegram issues an api_id, a number, and an api_hash, a string. These represent your application, and they should stay secret. Note the important difference from a bot token: api_id and api_hash by themselves do not log anyone in. They identify your app, and actually connecting still requires authorizing a specific user account through Telegram’s login flow, which involves a phone number and a confirmation code. That is a deliberate part of the model, because MTProto acts on behalf of a real account.

From credential to working integration

Having the credential is the start, not the finish. The next question for the Bot API path is how your bot hears about new messages, and there are two mechanisms.

• Long polling. Your code repeatedly calls the getUpdates method, and Telegram returns any new events. It is the simplest way to start because it needs no public URL, which makes it ideal for local development and small deployments.
• Webhooks. You register a public HTTPS endpoint with the setWebhook method, and Telegram pushes each update to it as it happens. This is the production-friendly approach because it removes the polling loop and scales better, but it requires a reachable, TLS-secured endpoint.

A common pattern is to develop against long polling and switch to a webhook for production. Whichever you choose, the flow is the same: receive an update, parse the message, decide on a response, and call the sendMessage method to reply. From those primitives you build commands, inline keyboards, media handling, and multi-step conversations.

Rate limits and other realities

Telegram is generous but not unlimited, and building as if limits do not exist is a reliable way to get messages dropped. As broad orders of magnitude, a bot should not send more than roughly one message per second to the same chat, bulk sending across many chats is capped at around thirty messages per second overall, and group broadcasts to the same group are limited further. Exceed these and Telegram returns a “too many requests” error with a retry delay you are expected to honor. Build a queue with backoff from the beginning rather than bolting it on after your first flood.

Two more constraints shape bot design. A bot cannot start a conversation with a user; the user must message the bot or add it to a group first, which is Telegram’s anti-spam stance. And a bot cannot see the phone numbers or full profiles of users it has not been explicitly given access to. Neither is a bug; both are guardrails you design around.

Keeping your credential safe

Whichever path you took, the credential is effectively the keys to the account, and leaks are the most common self-inflicted incident. A bot token committed to a public repository will often be found and abused within minutes, so keep both bot tokens and the api_id and api_hash pair in environment variables or a secrets manager, never in source control. If a token is exposed, revoke and reissue it through BotFather right away; for the client API you can reset the credentials from my.telegram.org. It is also worth scoping deployments so development and production use separate bots, which limits the blast radius if one is compromised and keeps test traffic out of your live metrics.

When one channel becomes several

Telegram is often the first messaging channel a product adds, and rarely the last. Once you have a Telegram bot answering support questions or pushing notifications, the same request tends to arrive for WhatsApp, then LinkedIn, then Instagram, and each platform has its own credential model, its own update mechanism, and its own limits. Rebuilding that plumbing per channel is where the effort quietly multiplies. A unified communication API such as Unipile addresses this by normalizing multiple messaging channels, Telegram among them, behind one interface, so your code works against a single message and conversation model instead of learning each platform’s quirks. It does not replace understanding Telegram’s rules, but it removes the per-channel reimplementation once you go beyond one platform. For a single Telegram bot, the native Bot API is perfectly sufficient; the unified route earns its place when your roadmap points at several channels.

A quick decision recap

To keep the two paths straight as you start:

• Building a bot that responds, notifies, or automates? Use the Bot API, get a token from BotFather, and treat that token as a secret.
• Building an app that acts as a real user with capabilities bots lack? Use MTProto, get api_id and api_hash from my.telegram.org, and expect a heavier auth flow.
• Prototyping? Long polling with getUpdates. Going to production? A webhook.
• Sending at volume? Add a rate-limited queue with retry handling before you need it.

Telegram earns its reputation for being approachable, and a first bot can be live in an afternoon. The developers who avoid the common frustrations are simply the ones who picked the right credential for the job at the very first fork, and everything downstream got easier because of it.