telegram-bot-ruby

Ruby wrapper for Telegram's Bot API.

Installation

Add following line to your Gemfile:

gem'telegram-bot-ruby'

And then execute:

$ bundle

Or install it system-wide:

$ gem install telegram-bot-ruby

Usage

First things first, you need to obtain a token for your bot. Then create your Telegram bot like this:

require'telegram/bot'token='YOUR_TELEGRAM_BOT_API_TOKEN'Telegram::Bot::Client.run(token)do |bot|
bot.listendo |message|
casemessage.textwhen'/start'bot.api.send_message(chat_id: message.chat.id,text: "Hello, #{message.from.first_name}")when'/stop'bot.api.send_message(chat_id: message.chat.id,text: "Bye, #{message.from.first_name}")endendend

Note that bot.api object implements Telegram Bot API methods as is. So you can invoke any method inside the block without any problems. All methods are available in both snake_case and camelCase notations.

Same thing about message object - it implements Message spec, so you always know what to expect from it.

Webhooks

If you are going to use webhooks instead of long polling, you need to implement your own webhook callbacks server. Take a look at this repo as an example.

Proxy

As some countries block access to Telegram, you can set up your own proxy and use it to access Telegram API. In this case you need to configure API url:

Telegram::Bot::Client.run(token,url: 'https://proxy.example.com')do |bot|
# ...end

Custom keyboards

You can use your own custom keyboards. Here is an example:

bot.listendo |message|
casemessage.textwhen'/start'question='London is a capital of which country?'# See more: https://core.telegram.org/bots/api#replykeyboardmarkupanswers=Telegram::Bot::Types::ReplyKeyboardMarkup.new(keyboard: [%w(AB),%w(CD)],one_time_keyboard: true)bot.api.send_message(chat_id: message.chat.id,text: question,reply_markup: answers)when'/stop'# See more: https://core.telegram.org/bots/api#replykeyboardremovekb=Telegram::Bot::Types::ReplyKeyboardRemove.new(remove_keyboard: true)bot.api.send_message(chat_id: message.chat.id,text: 'Sorry to see you go :(',reply_markup: kb)endend

Furthermore, you can ask user to share location or phone number using KeyboardButton:

bot.listendo |message|
kb=[Telegram::Bot::Types::KeyboardButton.new(text: 'Give me your phone number',request_contact: true),Telegram::Bot::Types::KeyboardButton.new(text: 'Show me your location',request_location: true)]markup=Telegram::Bot::Types::ReplyKeyboardMarkup.new(keyboard: kb)bot.api.send_message(chat_id: message.chat.id,text: 'Hey!',reply_markup: markup)end

Inline keyboards

Bot API 2.0 brought us new inline keyboards. Example:

bot.listendo |message|
casemessagewhenTelegram::Bot::Types::CallbackQuery# Here you can handle your callbacks from inline buttonsifmessage.data == 'touch'bot.api.send_message(chat_id: message.from.id,text: "Don't touch me!")endwhenTelegram::Bot::Types::Messagekb=[Telegram::Bot::Types::InlineKeyboardButton.new(text: 'Go to Google',url: 'https://google.com'),Telegram::Bot::Types::InlineKeyboardButton.new(text: 'Touch me',callback_data: 'touch'),Telegram::Bot::Types::InlineKeyboardButton.new(text: 'Switch to inline',switch_inline_query: 'some text')]markup=Telegram::Bot::Types::InlineKeyboardMarkup.new(inline_keyboard: kb)bot.api.send_message(chat_id: message.chat.id,text: 'Make a choice',reply_markup: markup)endend

Inline bots

If you are going to create inline bot, check the example below:

bot.listendo |message|
casemessagewhenTelegram::Bot::Types::InlineQueryresults=[[1,'First article','Very interesting text goes here.'],[2,'Second article','Another interesting text here.']].mapdo |arr|
Telegram::Bot::Types::InlineQueryResultArticle.new(id: arr[0],title: arr[1],input_message_content: Telegram::Bot::Types::InputTextMessageContent.new(message_text: arr[2]))endbot.api.answer_inline_query(inline_query_id: message.id,results: results)whenTelegram::Bot::Types::Messagebot.api.send_message(chat_id: message.chat.id,text: "Hello, #{message.from.first_name}!")endend

Now, with inline mode enabled, your message object can be an instance of Message, InlineQuery or ChosenInlineResult. That's why you need to check type of each message and decide how to handle it.

Using answer_inline_query you can send query results to user. results field must be an array of query result objects.

File upload

Your bot can even upload files (photos, audio, documents, stickers, video) to Telegram servers. Just like this:

bot.listendo |message|
casemessage.textwhen'/photo'bot.api.send_photo(chat_id: message.chat.id,photo: Faraday::UploadIO.new('~/Desktop/jennifer.jpg','image/jpeg'))endend

Logging

By default, bot doesn't log anything (uses NullLoger). You can change this behavior and provide your own logger class. See example below:

Telegram::Bot::Client.run(token,logger: Logger.new($stderr))do |bot|
bot.logger.info('Bot has been started')bot.listendo |message|
# ...endend

Connection adapters

Since version 0.5.0 we rely on faraday under the hood. You can use any of supported adapters (for example, net/http/persistent):

require'net/http/persistent'Telegram::Bot.configuredo |config|
config.adapter=:net_http_persistentend

Boilerplates

If you don't know how to setup database for your bot or how to use it with different languages here are some boilerplates which can help you to start faster:

• Ruby Telegram Bot boilerplate

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request