telegram

This package is a simple R wrapper around the Telegram Bot API.

It allows to send messages (text, Markdown, images, files) from R to your smartphone.

More infos on telegram's bot api can be found here and here.

If you need something more advanced and full-featured, take a look at telegram.bot package.

How to install the package?

For the stable version:

install.packages('telegram')

For the development one:

devtools::install_github('lbraglia/telegram')

First time setup

First you have to talk to the botfather to create a new bot; answer few questions regarding bot's name and you're ready to go.

After you've done, the botfather returns a token (which has to be kept secret) that lets you handle your bot; we need this token when creating the bot object on the R side. Following Hadley's API guidelines it's unsafe to type the token just in the R script. It's better to use enviroment variables set in .Renviron file.

So let's say you have named your bot RBot (it's the first question you've answered to the botfather); then put the following line with your token in your .Renviron:

R_TELEGRAM_BOT_RBot=123123:asdasdasd

If you follow the suggested R_TELEGRAM_BOT_ prefix convention you'll be able to use the bot_token function (otherwise you'll have to get these variable from Sys.getenv).

After you've finished these steps restart R in order to have working environment variables.

How to connect R with Telegram

Now you should be able to obtain a connection to your bot with these commands:

library(telegram)

## Create the bot object
bot <- TGBot$new(token = bot_token('RBot'))

## Now check bot connection it should print some of your bot's data
bot$getMe()

## Now, on the phone, find and say something to your bot to start a chat
## (and obtain a chat id).
## ...

## Here, check what you have inserted
bot$getUpdates()

## You're interested in the message.chat.id variable: in order to set a
## default chat_id for the following commands (to ease typing)
bot$set_default_chat_id(123456789)

After a bit using the package, you'll probably want to set the chat_id to your user id (or more generally, have something like an addressbook to store users' ids). If you put this in your .Renviron:

R_TELEGRAM_USER_me=123456789

you'll be able to use the user_id function, eg like this:

bot$set_default_chat_id(user_id('me'))

Specularly if you need to interact frequently with a group, you may want to add this to your .Renviron (group chat id are negative integers):

R_TELEGRAM_GROUP_fav_group=-123456789

you'll be able to use the group_id function, eg like this:

bot$set_default_chat_id(group_id('fav_group'))

How to connect using a proxy

Proxy parameters are expected to be a named list (names as parameters passed to httr::use_proxy:

## On initialization speci
prx <- list('url' = '123.45.6.78',
            'port' = 8080,
            'username' = 'user',
            'password' = 'password')
bot <- TGBot$new(token = bot_token('RBot'), proxy = prx)

##  .. or later (but before requests) ...
bot <- TGBot$new(token = bot_token('RBot'))
bot$set_proxy(proxy = prx)

## if you want to save default proxy values in .Renviron using the following
## schema
##
## R_TELEGRAM_PROXY_default_url=123.45.6.78
## R_TELEGRAM_PROXY_default_port=8080
## R_TELEGRAM_PROXY_default_username=user
## R_TELEGRAM_PROXY_default_password=password
## R_TELEGRAM_PROXY_default_auth=basic
##
## you can use the proxy utility function
##

proxy('default')

## which should return
## 
## $auth
## [1] "basic"
## 
## $password
## [1] "password"
## 
## $port
## [1] "8080"
## 
## $url
## [1] "123.45.6.78"
## 
## $username
## [1] "user"
##
##
## therefore, for a handy one-liner:

bot <- TGBot$new(token = bot_token('RBot'), proxy = proxy('default'))

Examples of methods currently implemented

Once you've followed the previous section, run the following commands and look at your phone.

## ------------------
## Send some messages
## ------------------
bot$sendMessage('This is plain text')

## Markdown support (version 2 via parse_mode = 'markdownv2')
md <- "
*bold* _italic_ [r-project](http://r-project.org) 
try `x <- rnorm(100)` at the console ...
you can have
    ``` 
    x <- runif(100)
    mean(x)
    ```
too
"
bot$sendMessage(md, parse_mode = 'markdown')
## HTML support (eg)
html_message <- "
<b>bold</b>, <i>italic</i>, <u>underline</u>,
<s>strikethrough</s>,
<a href='http://www.example.com/'>inline URL</a>
<a href='tg://user?id=123456789'>inline mention of a user</a>
<code>inline fixed-width code</code>
<pre>pre-formatted fixed-width code block</pre>
"
bot$sendMessage(html_message, parse_mode = 'html')

## -------------------
## Send an image/photo
## -------------------
png('test.png')
plot(rnorm(100))
dev.off()
bot$sendPhoto('test.png', caption = 'This is my awesome graph')

## ---------------------------------
## Send a document (can be any file)
## ---------------------------------
help(TGBot, help_type = 'pdf')
bot$sendDocument('TGBot.pdf')

## ---------------
## Send a location
## ---------------
bot$sendLocation(44.699, 10.6297)

## --------------
## Send a sticker
## --------------
bot$sendSticker(system.file('r_logo.webp', package = 'telegram'))

## ------------
## Send a video
## ------------
library(animation)
saveVideo({
    set.seed(1)
    nmax <- 10
    ani.options(interval = 0.4, nmax = nmax)
    x <- c()
    for (i in 1:nmax){
        x <- c(x, rnorm(1))
        plot(cumsum(x), lty = 2, xlim = c(1, nmax), ylim = c(-5, 5))
        abline(h = 0, col = 'red')
    }
}, video.name = 'animation.mp4')
bot$sendVideo('animation.mp4')

## --------------------
## Send mp3 audio files
## --------------------
bot$sendAudio(system.file('audio_test.mp3', package = 'telegram'),
              performer = 'espeak (http://espeak.sf.net)')

## ------------------------------------
## Send voice (opus encoded .ogg files)
## ------------------------------------
bot$sendVoice(system.file('voice_test.ogg', package = 'telegram'))

## -----------------------------------------------------------------
## Tell the user what's happening on the bot's side (for long tasks)
## -----------------------------------------------------------------
bot$sendChatAction('typing')
bot$sendChatAction('upload_photo')
bot$sendChatAction('record_video')
bot$sendChatAction('upload_video')
bot$sendChatAction('record_voice')
bot$sendChatAction('upload_voice')
bot$sendChatAction('upload_document')
bot$sendChatAction('find_location')
bot$sendChatAction('record_video_note')
bot$sendChatAction('upload_video_note')

## ----------------------------------------------------------
## Roll a dice (animation of a random number between 1 and 6)
## ----------------------------------------------------------
bot$sendDice()

## ------------
## Start a poll
## ------------
bot$sendPoll(question = 'What is your gender?',
             options = c('Female', 'Male'))
bot$sendPoll(question = "What was the color of Napoleon's horse?",
             options = c('black', 'yellow', 'white', 'green', 'pois'),
             is_anonymous = FALSE,
             type = 'quiz',
             correct_option_id = 2) ## it's 0 based so 2 is the third
                                    ## option (white)
bot$sendPoll(question = "Which genres of music do you listen to the most?",
             options = c('blues', 'rock', 'metal', 'rnb', 'jazz', 'pop'),
             is_anonymous = FALSE,
             allows_multiple_answers = TRUE)

## -----------------
## Forward a message
## -----------------
bot$forwardMessage(from_chat_id = 123456,
                   chat_id = 123456,
                   message_id = 35)

## ---------------------------
## Get info about user's photo
## ---------------------------
bot$getUserProfilePhotos(user_id('me')) # <- alternatively, message.from.id variable in getUpdates

## ------------------------------------
## Obtain files on the Telegram servers
## ------------------------------------
bot$getFile('asdasdasdqweqweqwe-UdYAAgI', # <- file_id from getUserProfilePhotos
            'me_small.png')