The add operator

Ernest Benedito

2022-09-07

The add operator (+, or more formally +.TelegramObject) is an S3 method for class TelegramObject that enables you to add any kind of Handler to an Updater’s Dispatcher.

Example

Say you want to build a bot with a simple handler for the /start command:

start <- function(bot, update){
  bot$sendMessage(chat_id = update$message$chat_id,
                  text = sprintf("Hello %s!",
                                 update$message$from$first_name))
}

start_handler <- CommandHandler("start", start)

You can then build your updater with:

updater <- Updater("TOKEN") + start_handler

As things start to get more complex, you can chain multiple handlers in a single call:

echo <- function(bot, update){
  bot$sendMessage(chat_id = update$message$chat_id,
                  text = update$message$text)
}

updater <- Updater("TOKEN") + CommandHandler("start", start) + MessageHandler(echo, MessageFilters$text)

And keep adding…

caps <- function(bot, update, args){
  if (length(args > 0L)){
    text_caps <- toupper(paste(args, collapse = " "))
    bot$sendMessage(chat_id = update$message$chat_id,
                    text = text_caps) 
  }
}

updater <- updater + CommandHandler("caps", caps, pass_args = TRUE)

Give it a try! Start polling the updater:

updater$start_polling()

And send /start to the bot, /caps foo or just a simple text.

How it works

The operator is indeed calling the add_handler method from an Updater’s Dispatcher. Then:

updater <- updater + start_handler

Is equivalent to:

updater$dispatcher$add_handler(start_handler)

Also, it works with Dispatcher objects:

dispatcher <- updater$dispatcher
dispatcher <- dispatcher + start_handler

So, all in all, the +.TelegramObject operator simplifies the construction of an Updater. However, if you want to add a handler with advanced settings, let’s say by controlling the group in which it is placed, you will need to make an add_handler call.