Develop a 'Telegram Bot' with R

Provides a pure interface for the 'Telegram Bot API' < http://core.telegram.org/bots/api>. In addition to the pure API implementation, 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.


CRAN Downloads Travis CI Status AppVeyor Build Status Codecov License

This package provides a pure R interface for the Telegram Bot API. In addition to the pure API implementation, 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.

Installation

You can install telegram.bot from CRAN:

install.packages("telegram.bot")

Or the development version from GitHub:

# install.packages("devtools")
devtools::install_github("ebeneditos/telegram.bot")

Usage

You can quickly build a chatbot with a few lines:

library(telegram.bot)
 
start <- function(bot, update){
  bot$sendMessage(chat_id = update$message$chat$id,
                  text = sprintf("Hello %s!", update$message$from$first_name))
}
 
updater <- Updater("TOKEN") + CommandHandler("start", start)
 
updater$start_polling() # Send '/start' to the bot

If you don't have a TOKEN, you can follow the steps explained below to generate one.

Telegram API Methods

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 some examples:

# Initialize bot
bot <- Bot(token = "TOKEN")
 
# Get bot info
print(bot$getMe())
 
# Get updates
updates <- bot$getUpdates()
 
# Retrieve your chat id
# Note: you should text the bot before calling 'getUpdates'
chat_id <- updates[[1L]]$from_chat_id()
 
# Send message
bot$sendMessage(chat_id = chat_id,
                text = "foo *bold* _italic_",
                parse_mode = "Markdown")
 
# Send photo
bot$sendPhoto(chat_id = chat_id,
              photo = "https://telegram.org/img/t_logo.png")
 
# Send audio
bot$sendAudio(chat_id = chat_id,
              audio = "http://www.largesound.com/ashborytour/sound/brobob.mp3")
 
# Send document
bot$sendDocument(chat_id = chat_id,
                 document = "https://github.com/ebeneditos/telegram.bot/raw/gh-pages/docs/telegram.bot.pdf")
 
# Send sticker
bot$sendSticker(chat_id = chat_id,
                sticker = "https://www.gstatic.com/webp/gallery/1.webp")
 
# Send video
bot$sendVideo(chat_id = chat_id,
              video = "http://techslides.com/demos/sample-videos/small.mp4")
 
# Send gif
bot$sendAnimation(chat_id = chat_id,
                  animation = "https://media.giphy.com/media/sIIhZliB2McAo/giphy.gif")
 
# Send location
bot$sendLocation(chat_id = chat_id,
                 latitude = 51.521727,
                 longitude = -0.117255)
 
# Send chat action
bot$sendChatAction(chat_id = chat_id,
                   action = "typing")
 
# Get user profile photos
photos <- bot$getUserProfilePhotos(user_id = chat_id)
 
# Download user profile photo
file_id <- photos$photos[[1L]][[1L]]$file_id
bot$getFile(file_id, destfile = "photo.jpg")

Note that you can also send local files by passing their path instead of an URL. Additionaly, all methods accept their equivalent snake_case syntax (e.g. bot$get_me() is equivalent to bot$getMe()).

Generating an Access Token

To make it work, you'll need an access TOKEN (it should look something like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11). If you don't have it, you have to talk to @BotFather and follow a few simple steps (described here).

Recommendation: Following Hadley's API guidelines it's unsafe to type the TOKEN just in the R script. It's better to use environment variables set in .Renviron file.

So let's say you have named your bot RTelegramBot; you can open the .Renviron file with the R command:

file.edit(path.expand(file.path("~", ".Renviron")))

And put the following line with your TOKEN in your .Renviron:

R_TELEGRAM_BOT_RTelegramBot=TOKEN

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). Finally, restart R and you can then create the Updater object as:

updater <- Updater(token = bot_token("RTelegramBot"))

Getting Started

To get you started with telegram.bot, we recommend to take a look at its Wiki:

You can also check these other resources:

If you have any other doubt about the package, you can post a question on Stack Overflow under the r-telegram-bot tag or directly e-mail the package's maintainer.

Contributing

The package is in a starting phase, so contributions of all sizes are very welcome. Please:

Attribution

This package is inspired by Python's library python-telegram-bot, specially by its submodule telegram.ext.

News

telegram.bot 2.3.1

  • Bug affecting reply_markup parameter from editMessageReplyMarkup() fixed (#9). Thanks to Diogo Tayt-son for reporting.

telegram.bot 2.3.0

  • Processing of updates through Updater() has been optimized.
  • Bug affecting callback query answering fixed. Thanks to Nikita Strezhnev for reporting.

telegram.bot 2.2.0

  • New S3 methods:
    • + method for class TelegramObject, which eases the Updater construction (see The add operator).
    • !, & and | methods for class BaseFilter, which enables combining filters (see Advanced Filters).
  • New destfile parameter for getFile() to download files to a local path.
  • New username parameter for CommandHandler() with examples.
  • New ErrorHandler() with examples.
  • New from_chat_id() and from_user_id() methods for Update().
  • Vignettes update:
    • Added The add operator.
    • Substituted Custom filters vignette with Advanced filters.
  • Minor bug fixes.

telegram.bot 2.1.0

  • Fixed a bug that affected sending local files.
  • Renamed Filters for MessageFilters to avoid masking from utils::Filters.
  • Added Set a Proxy vignette and examples.

telegram.bot 2.0.0

  • Bot() has been totally updated so to be independent from TGBot. Therefore, all its API methods have been implemented, optimized and updated (e.g. adding timeout argument to getUpdates(), so to use Long Polling). Additionally, new methods have been added, the full list is:
    • answerCallbackQuery()
    • answerInlineQuery()
    • deleteMessage()
    • deleteWebhook()
    • editMessageReplyMarkup()
    • forwardMessage()
    • getFile()
    • getMe()
    • getUpdates()
    • getUserProfilePhotos()
    • getWebhookInfo()
    • leaveChat()
    • sendAnimation()
    • sendAudio()
    • sendChatAction()
    • sendDocument()
    • sendLocation()
    • sendMessage()
    • sendPhoto()
    • sendSticker()
    • sendVideo()
    • sendVideoNote()
    • sendVoice()
    • setWebhook()
  • New parameter reply_markup from sendMessage() for keyboard displaying, with its objects:
    • ReplyKeyboardMarkup
    • InlineKeyboardMarkup
    • ReplyKeyboardRemove
    • ForceReply
  • Support of inline mode with answerInlineQuery() and the InlineQueryResult object.
  • New request_config parameter for Bot() and Updater(), which allows you to set additional configuration settings to be passed to the bot's POST requests, useful for users who would like to control the default timeouts and/or control the proxy used for HTTP communication.
  • New clean_updates(), set_token(), bot_token() and user_id().
  • Vignettes added:
    • Introduction
    • Building a Bot
    • Basic functionalities
    • Custom filters
  • LICENSE updated from LGPL-3 to GPL-3.
  • Minor bug fixes.

telegram.bot 1.0.0

  • First release on CRAN.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("telegram.bot")

2.3.1 by Ernest Benedito, 6 months ago


http://github.com/ebeneditos/telegram.bot


Report a bug at http://github.com/ebeneditos/telegram.bot/issues


Browse source code at https://github.com/cran/telegram.bot


Authors: Ernest Benedito [aut, cre]


Documentation:   PDF Manual  


GPL-3 license


Imports curl, httr, jsonlite, R6

Suggests covr, knitr, rmarkdown, testthat


See at CRAN