If you are new to Telegram bots, we recommend checking out our Introduction to Bots first.
You may also find the Bot API Manual useful.
Creating Telegram bots is super-easy, but you will need at least some skills at computer programming. In order for a bot to work, set up a bot account with @BotFather, then connect it to your backend server via our API.
Unfortunately, there are no out-of-the-box ways to create a working bot if you are not a developer. But we're sure you'll soon find plenty of bots created by other people to play with.
Here are two sample bots, both written in PHP:
Many members of our community are building bots and publishing sources.
We're collecting them on this page »
Ping us on @BotSupport if you've built a bot and would like to share it with others.
The bot API is still pretty young. There are many potential features to consider and implement. We'll be studying what people do with their bots for a while to see which directions will be most important for the platform.
All bot developers are welcome to share ideas for our Bot API with our @BotSupport account.
1. All bots, regardless of settings, will receive:
2. Bot admins and bots with privacy mode disabled will receive all messages except messages sent by other bots.
3. Bots with privacy mode enabled will receive:
Note that each particular message can only be available to one privacy-enabled bot at a time, i.e., a reply to bot A containing an explicit command for bot B or sent via bot C will only be available to bot A. Replies have the highest priority.
Bots talking to each other could potentially get stuck in unwelcome loops. To avoid this, we decided that bots will not be able to see messages from other bots regardless of mode.
There are currently two ways of getting updates. You can either use long polling or Webhooks. Please note that it's not possible to get updates via long polling while an outgoing Webhook is set.
The getUpdates method returns the earliest 100 unconfirmed updates. To confirm an update, use the offset parameter when calling getUpdates like this:
offset = update_id of last processed update + 1
All updates with update_id less than or equal to offset will be marked as confirmed on the server and will no longer be returned.
If you've set up your webhook successfully, but are not getting any updates, please remember:
Please check out this new WEBHOOK GUIDE to learn all there is to know about webhooks!
Please take a look at this self-signed certificate guide we made just for you. If you've read it and still have a question, ping us on botsupport.
If you'd like to make sure that the Webhook request comes from Telegram, we recommend using a secret path in the URL you give us, e.g. www.example.com/your_token. Since nobody else knows your bot's token, you can be pretty sure it's us.
This is possible if you're using webhooks. The upside is that you need less requests, the downside — that in this case it's not possible to know that such a request was successful or get its result.
Whenever you receive a webhook update, you have two options:
1. Issue POST to https://api.tlgr.org/bot<token>/method
2. Reply directly and give method as JSON payload in the reply
You may also want to look at our sample HelloBot, it offers a PHP implementation of this.
Use the getFile method. Please note that this will only work with files of up to 20 MB in size.
Bots can currently send files of any type of up to 50 MB in size, so yes, very large files won't work for now. Sorry. This limit may be changed in the future.
Yes, file_ids can be treated as persistent.
When sending messages inside a particular chat, avoid sending more than one message per second. We may allow short bursts that go over this limit, but eventually you'll begin receiving 429 errors.
If you're sending bulk notifications to multiple users, the API will not allow more than 30 messages per second or so. Consider spreading out notifications over large intervals of 8—12 hours for best results.
Also note that your bot will not be able to send more than 20 messages per minute to the same group.
Unfortunately, at this moment we don't have methods for sending bulk messages, e.g. notifications. We may add something along these lines in the future.
In order to avoid hitting our limits when sending out mass notifications, consider spreading them over longer intervals, e.g. 8-12 hours. The API will not allow bulk notifications to more than ~30 users per second, if you go over that, you'll start getting 429 errors.
See also: How to avoid hitting limits?
If you've got questions that are not answered on this page, ping us at @BotSupport in Telegram.
We welcome any suggestions for the Bot Platform and API.