Ruby wrapper for Telegram's Bot API.
Since v1.0 telegram-bot-ruby uses dry-struct
instead of virtus.
This means that type objects are now immutable and you can't change them after initialization:
# This won't work
kb = Telegram::Bot::Types::ReplyKeyboardRemove.new
kb.remove_keyboard = true
# You have to set attributes in constructor instead
kb = Telegram::Bot::Types::ReplyKeyboardRemove.new(remove_keyboard: true)Please make sure it doesn't break your existing code before upgrading to 1.0.
Add following line to your Gemfile:
gem 'telegram-bot-ruby', '~> 1.0'And then execute:
bundleOr install it system-wide:
gem install telegram-bot-rubyFirst 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.listen do |message|
case message.text
when '/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}")
end
end
endNote 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.
If you need to start a bot in development mode you have to pass environment: :test:
Telegram::Bot::Client.run(token, environment: :test) do |bot|
# ...
endSame thing about message object: it implements Message spec,
so you always know what to expect from it.
To gracefully stop the bot, for example by INT signal (Ctrl-C), call the bot.stop method:
bot = Telegram::Bot::Client.new(token)
Signal.trap('INT') do
bot.stop
end
bot.listen do |message|
# it will be in an infinity loop until `bot.stop` command
# (with a small delay for the current `fetch_updates` request)
endIf 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.
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|
# ...
endYou can use your own custom keyboards. Here is an example:
bot.listen do |message|
case message.text
when '/start'
question = 'London is a capital of which country?'
# See more: https://core.telegram.org/bots/api#replykeyboardmarkup
answers =
Telegram::Bot::Types::ReplyKeyboardMarkup.new(
keyboard: [
[{ text: 'A' }, { text: 'B' }],
[{ text: 'C' }, { text: 'D' }]
],
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#replykeyboardremove
kb = 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)
end
endFurthermore, you can ask user to share location or phone number using KeyboardButton:
bot.listen do |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)
endBot API 2.0 brought us new inline keyboards. Example:
bot.listen do |message|
case message
when Telegram::Bot::Types::CallbackQuery
# Here you can handle your callbacks from inline buttons
if message.data == 'touch'
bot.api.send_message(chat_id: message.from.id, text: "Don't touch me!")
end
when Telegram::Bot::Types::Message
kb = [[
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)
end
endIf you are going to create inline bot, check the example below:
bot.listen do |message|
case message
when Telegram::Bot::Types::InlineQuery
results = [
['1', 'First article', 'Very interesting text goes here.'],
['2', 'Second article', 'Another interesting text here.']
].map do |arr|
Telegram::Bot::Types::InlineQueryResultArticle.new(
id: arr[0],
title: arr[1],
input_message_content: Telegram::Bot::Types::InputTextMessageContent.new(message_text: arr[2])
)
end
bot.api.answer_inline_query(inline_query_id: message.id, results: results)
when Telegram::Bot::Types::Message
bot.api.send_message(chat_id: message.chat.id, text: "Hello, #{message.from.first_name}!")
end
endNow, 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.
Your bot can even upload files (photos, audio, documents, stickers, video) to Telegram servers. Just like this:
bot.listen do |message|
case message.text
when '/photo'
path_to_photo = File.expand_path('~/Desktop/jennifer.jpg')
bot.api.send_photo(chat_id: message.chat.id, photo: Faraday::UploadIO.new(path_to_photo, 'image/jpeg'))
end
endBy 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.listen do |message|
# ...
end
endSince 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.configure do |config|
config.adapter = :net_http_persistent
endIf 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:
- Fork it.
- Create your feature branch (
git checkout -b my-new-feature). - Commit your changes (
git commit -am 'Add some feature'). - Push to the branch (
git push origin my-new-feature). - Create a new Pull Request.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent