In this vignette you will learn how the Telegram Bot API works and how you can connect to it from R, with the following sections:
First, you must have or create a
Telegram account. Second, you’ll need to create a Telegram Bot in
order to get an Access Token. You can do so by talking to @BotFather and following a few simple steps.
Telegram bots can receive messages or commands. The
former are simply text that you send as if you were sending a message to
another person, while the latter are prefixed with a
character. To create a new bot, send the following command to
BotFather as a chat (exactly as if you were talking to another
person on Telegram):
You should get a reply instantly that asks you to choose a name for your Bot. You have to send then the name you want for the bot, which can be anyone, for instance:
BotFather will now ask you to pick a username for your Bot.
This username has to end in
bot, and be globally unique. In
this tutorial we’ll indicate the Bot’s username with
<your-bot-username>, so you’ll have to substitute
your chosen username wherever relevant from now on. Send your chosen
username to BotFather:
After doing so, BotFather will send you a “Congratulations” message, which will include a token. The token should look something like this:
For the rest of this tutorial, we’ll indicate where you need to put
your token by using
<your-bot-token> or just
TOKEN. Take note of the token, as you’ll need it in the
code that you are about to write.
You can control your Bot by sending HTTPS requests to Telegram. This
means that the simplest way to interact with your Bot is through a web
browser. By visiting different URLs, you send different commands to your
Bot. The simplest command is one where you get information about your
Bot. Visit the following URL in your browser (substituting the
TOKEN that you got before):
The first part of the URL indicates that you want to communicate with
the Telegram API (
api.telegram.org). You follow this with
/bot to say that you want to send a command to your Bot,
and immediately after you add your
TOKEN to identify which
bot you want to send the command to and to prove that you own it.
Finally, you specify the command that you want to send
/getMe) which in this case just returns basic information
about our Bot using JSON.
The simplest way to retrieve messages sent to your Bot is through the
If you this page you’ll get a JSON response of all the new messages sent to your Bot. Try sending a message to your Bot and visit that URL.
The final API call that we’ll try out in the browser is that used to
send a message. To do this, you need the chat ID for the chat where you
want to send the message. There are a bunch of different IDs in the JSON
response from the
getUpdates call, so make sure you get the
right one. It’s the id field which is inside the chat field. Once you
have this ID, visit the following URL in your browser, substituting
<chat-id> for your chat ID.
Once you’ve visited this URL, you should see a message from your Bot sent to your which says “TestReply”.
You could program with R some functions that send these HTTPS
requests and processes its responses. Fortunately, there is a package
that allows you to do that:
telegram.bot. It uses
jsonlite packages to do such work.
Additionally, it features a number of tools to make the development of
Telegram bots with R easy and straightforward, providing an easy-to-use
interface that takes some work off the programmer.
telegram.bot package consists of several
R6 classes, and the API is exposed via the
class. The methods names are equivalents of the methods described in the
official Telegram Bot
API. The exact snake_case method names are also available
for your convenience. So for example
Bot$get_updates is the
To get a feeling for the API and how to use it with
telegram.bot, we will reproduce the URL based example we
just saw, done with R with this package.
First, create an instance of the
Bot class, where
TOKEN should be replaced by the API token you received from
# install.packages("telegram.bot") library(telegram.bot) <- Bot(token = "TOKEN")bot
To check if your credentials are correct, call the getMe API method:
Note: Bots can’t initiate conversations with users.
A user must either add them to a group or send them a message first.
People can use
or username search to find your bot (searching for
@<your-bot-username> in any of the Telegram
You can get updates from your bot with the command:
This will retrieve a
list generated from the JSON
response from the server. In order to send a response, you can do it so
with the following command:
<- "CHAT_ID" # you can retrieve it from bot$getUpdates() after sending a message to the bot chat_id $sendMessage(chat_id = chat_id, text = "TestReply")bot
As you see, one of the core instances from the package is
Bot, which represents a Telegram Bot. You can find a full
list of the Telegram API methods implemented in its documentation
?Bot), but here there are a few more examples:
# Send message $sendMessage(chat_id, bottext = "foo *bold* _italic_", parse_mode = "Markdown" ) # Send photo $sendPhoto(chat_id, botphoto = "https://telegram.org/img/t_logo.png" ) # Send audio $sendAudio(chat_id, botaudio = "http://www.largesound.com/ashborytour/sound/brobob.mp3" ) # Send document $sendDocument(chat_id, botdocument = paste0( "https://github.com/ebeneditos/telegram.bot/raw/gh-pages/docs/", "telegram.bot.pdf" ) ) # Send sticker $sendSticker(chat_id, botsticker = "https://www.gstatic.com/webp/gallery/1.webp" ) # Send video $sendVideo(chat_id, botvideo = "http://techslides.com/demos/sample-videos/small.mp4" ) # Send gif $sendAnimation(chat_id, botanimation = "https://media.giphy.com/media/sIIhZliB2McAo/giphy.gif" ) # Send location $sendLocation(chat_id, botlatitude = 51.521727, longitude = -0.117255 ) # Send chat action $sendChatAction(chat_id, botaction = "typing" ) # Get user profile photos <- bot$getUserProfilePhotos(user_id = chat_id) photos # Download user profile photo <- photos$photos[[1L]][[1L]]$file_id file_id $getFile(file_id, destfile = "photo.jpg")bot
Note that you can also send local files by passing their path instead
of an URL. Additionally, all methods accept their equivalent
snake_case syntax (e.g.