{"id":13461897,"url":"https://github.com/atipugin/telegram-bot-ruby","last_synced_at":"2025-05-15T14:04:07.434Z","repository":{"id":34280945,"uuid":"38169179","full_name":"atipugin/telegram-bot-ruby","owner":"atipugin","description":"Ruby wrapper for Telegram's Bot API","archived":false,"fork":false,"pushed_at":"2025-02-13T04:37:12.000Z","size":456,"stargazers_count":1386,"open_issues_count":0,"forks_count":223,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-04-12T13:57:36.324Z","etag":null,"topics":["ruby","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":"https://core.telegram.org/bots/api","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atipugin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-06-27T17:40:29.000Z","updated_at":"2025-04-07T13:09:30.000Z","dependencies_parsed_at":"2023-12-03T05:23:52.731Z","dependency_job_id":"fc23dcea-8bf7-4fb0-8aa6-e66efb284b24","html_url":"https://github.com/atipugin/telegram-bot-ruby","commit_stats":null,"previous_names":["atipugin/telegram-bot"],"tags_count":76,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atipugin%2Ftelegram-bot-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atipugin%2Ftelegram-bot-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atipugin%2Ftelegram-bot-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atipugin%2Ftelegram-bot-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atipugin","download_url":"https://codeload.github.com/atipugin/telegram-bot-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254355334,"owners_count":22057354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ruby","telegram","telegram-bot"],"created_at":"2024-07-31T12:00:26.882Z","updated_at":"2025-05-15T14:04:07.390Z","avatar_url":"https://github.com/atipugin.png","language":"Ruby","readme":"# telegram-bot-ruby\n\nRuby wrapper for [Telegram's Bot API](https://core.telegram.org/bots/api).\n\n[![Gem Version](https://badge.fury.io/rb/telegram-bot-ruby.svg)](http://badge.fury.io/rb/telegram-bot-ruby)\n[![Build Status](https://github.com/atipugin/telegram-bot-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/atipugin/telegram-bot-ruby/actions)\n[![Maintainability](https://api.codeclimate.com/v1/badges/7e61fbf5bec86e118fb1/maintainability)](https://codeclimate.com/github/atipugin/telegram-bot-ruby/maintainability)\n[![Say Thanks!](https://img.shields.io/badge/Say%20Thanks!-🦉-1EAEDB.svg)](https://saythanks.io/to/atipugin)\n\n## 🚧 Upgrading to 1.0\n\nSince v1.0 `telegram-bot-ruby` uses [`dry-struct`](https://github.com/dry-rb/dry-struct)\ninstead of [`virtus`](https://github.com/solnic/virtus).\nThis means that type objects are now immutable and you can't change them after initialization:\n\n```ruby\n# This won't work\nkb = Telegram::Bot::Types::ReplyKeyboardRemove.new\nkb.remove_keyboard = true\n\n# You have to set attributes in constructor instead\nkb = Telegram::Bot::Types::ReplyKeyboardRemove.new(remove_keyboard: true)\n```\n\nPlease make sure it doesn't break your existing code before upgrading to 1.0.\n\n## Installation\n\nAdd following line to your Gemfile:\n\n```ruby\ngem 'telegram-bot-ruby', '~\u003e 2.1'\n```\n\nAnd then execute:\n\n```shell\nbundle\n```\n\nOr install it system-wide:\n\n```shell\ngem install telegram-bot-ruby\n```\n\n## Usage\n\nFirst things first, you need to [obtain a token](https://core.telegram.org/bots#6-botfather) for your bot.\nThen create your Telegram bot like this:\n\n```ruby\nrequire 'telegram/bot'\n\ntoken = 'YOUR_TELEGRAM_BOT_API_TOKEN'\n\nTelegram::Bot::Client.run(token) do |bot|\n  bot.listen do |message|\n    case message.text\n    when '/start'\n      bot.api.send_message(chat_id: message.chat.id, text: \"Hello, #{message.from.first_name}\")\n    when '/stop'\n      bot.api.send_message(chat_id: message.chat.id, text: \"Bye, #{message.from.first_name}\")\n    end\n  end\nend\n```\n\nNote that `bot.api` object implements\n[Telegram Bot API methods](https://core.telegram.org/bots/api#available-methods) as is.\nSo you can invoke any method inside the block without any problems.\nAll methods are available in both *snake_case* and *camelCase* notations.\n\nIf you need to start a bot in development mode you have to pass `environment: :test`:\n\n```ruby\nTelegram::Bot::Client.run(token, environment: :test) do |bot|\n  # ...\nend\n```\n\nSame thing about `message` object: it implements [Message](https://core.telegram.org/bots/api#message) spec,\nso you always know what to expect from it.\n\nTo gracefully stop the bot, for example by `INT` signal (Ctrl-C), call the `bot.stop` method:\n\n```ruby\nbot = Telegram::Bot::Client.new(token)\n\nSignal.trap('INT') do\n  bot.stop\nend\n\nbot.listen do |message|\n  # it will be in an infinity loop until `bot.stop` command\n  # (with a small delay for the current `fetch_updates` request)\nend\n```\n\n## Webhooks\n\nIf you are going to use [webhooks](https://core.telegram.org/bots/api#setwebhook)\ninstead of [long polling](https://core.telegram.org/bots/api#getupdates),\nyou need to implement your own webhook callbacks server.\nTake a look at [this repo](https://github.com/solyaris/BOTServer) as an example.\n\n## Proxy\n\nAs some countries block access to Telegram, you can set up your own proxy and use it to access Telegram API.\nIn this case you need to configure API URL:\n\n```ruby\nTelegram::Bot::Client.run(token, url: 'https://proxy.example.com') do |bot|\n  # ...\nend\n```\n\n## Custom keyboards\n\nYou can use your own [custom keyboards](https://core.telegram.org/bots#keyboards).\nHere is an example:\n\n```ruby\nbot.listen do |message|\n  case message.text\n  when '/start'\n    question = 'London is a capital of which country?'\n    # See more: https://core.telegram.org/bots/api#replykeyboardmarkup\n    answers =\n        Telegram::Bot::Types::ReplyKeyboardMarkup.new(\n          keyboard: [\n            [{ text: 'A' }, { text: 'B' }],\n            [{ text: 'C' }, { text: 'D' }]\n          ],\n          one_time_keyboard: true\n        )\n    bot.api.send_message(chat_id: message.chat.id, text: question, reply_markup: answers)\n  when '/stop'\n    # See more: https://core.telegram.org/bots/api#replykeyboardremove\n    kb = Telegram::Bot::Types::ReplyKeyboardRemove.new(remove_keyboard: true)\n    bot.api.send_message(chat_id: message.chat.id, text: 'Sorry to see you go :(', reply_markup: kb)\n  end\nend\n```\n\nFurthermore, you can ask user to share location or phone number using `KeyboardButton`:\n\n```ruby\nbot.listen do |message|\n  kb = [[\n    Telegram::Bot::Types::KeyboardButton.new(text: 'Give me your phone number', request_contact: true),\n    Telegram::Bot::Types::KeyboardButton.new(text: 'Show me your location', request_location: true)\n  ]]\n  markup = Telegram::Bot::Types::ReplyKeyboardMarkup.new(keyboard: kb)\n  bot.api.send_message(chat_id: message.chat.id, text: 'Hey!', reply_markup: markup)\nend\n```\n\n## Inline keyboards\n\n[Bot API 2.0](https://core.telegram.org/bots/2-0-intro) brought us new inline keyboards.\nExample:\n\n```ruby\nbot.listen do |message|\n  case message\n  when Telegram::Bot::Types::CallbackQuery\n    # Here you can handle your callbacks from inline buttons\n    if message.data == 'touch'\n      bot.api.send_message(chat_id: message.from.id, text: \"Don't touch me!\")\n    end\n  when Telegram::Bot::Types::Message\n    kb = [[\n      Telegram::Bot::Types::InlineKeyboardButton.new(text: 'Go to Google', url: 'https://google.com'),\n      Telegram::Bot::Types::InlineKeyboardButton.new(text: 'Touch me', callback_data: 'touch'),\n      Telegram::Bot::Types::InlineKeyboardButton.new(text: 'Switch to inline', switch_inline_query: 'some text')\n    ]]\n    markup = Telegram::Bot::Types::InlineKeyboardMarkup.new(inline_keyboard: kb)\n    bot.api.send_message(chat_id: message.chat.id, text: 'Make a choice', reply_markup: markup)\n  end\nend\n```\n\n## Inline bots\n\nIf you are going to create [inline bot](https://core.telegram.org/bots/inline), check the example below:\n\n```ruby\nbot.listen do |message|\n  case message\n  when Telegram::Bot::Types::InlineQuery\n    results = [\n      ['1', 'First article', 'Very interesting text goes here.'],\n      ['2', 'Second article', 'Another interesting text here.']\n    ].map do |arr|\n      Telegram::Bot::Types::InlineQueryResultArticle.new(\n        id: arr[0],\n        title: arr[1],\n        input_message_content: Telegram::Bot::Types::InputTextMessageContent.new(message_text: arr[2])\n      )\n    end\n\n    bot.api.answer_inline_query(inline_query_id: message.id, results: results)\n  when Telegram::Bot::Types::Message\n    bot.api.send_message(chat_id: message.chat.id, text: \"Hello, #{message.from.first_name}!\")\n  end\nend\n```\n\nNow, with `inline` mode enabled, your `message` object can be an instance of\n[Message](https://core.telegram.org/bots/api#message),\n[InlineQuery](https://core.telegram.org/bots/api#inlinequery) or\n[ChosenInlineResult](https://core.telegram.org/bots/api#choseninlineresult).\nThat's why you need to check type of each message and decide how to handle it.\n\nUsing `answer_inline_query` you can send query results to user.\n`results` field must be an array of [query result objects](https://core.telegram.org/bots/api#inlinequeryresult).\n\n## File upload\n\nYour bot can even upload files\n([photos](https://core.telegram.org/bots/api#sendphoto),\n[audio](https://core.telegram.org/bots/api#sendaudio),\n[documents](https://core.telegram.org/bots/api#senddocument),\n[stickers](https://core.telegram.org/bots/api#sendsticker),\n[video](https://core.telegram.org/bots/api#sendvideo))\nto Telegram servers.\nJust like this:\n\n```ruby\nbot.listen do |message|\n  case message.text\n  when '/photo'\n    path_to_photo = File.expand_path('~/Desktop/jennifer.jpg')\n    bot.api.send_photo(chat_id: message.chat.id, photo: Faraday::UploadIO.new(path_to_photo, 'image/jpeg'))\n  end\nend\n```\n\n## Logging\n\nBy default, bot doesn't log anything (uses `NullLoger`).\nYou can change this behavior and provide your own logger class.\nSee example below:\n\n```ruby\nTelegram::Bot::Client.run(token, logger: Logger.new($stderr)) do |bot|\n  bot.logger.info('Bot has been started')\n  bot.listen do |message|\n    # ...\n  end\nend\n```\n\n## Connection adapters\n\nSince version `0.5.0` we rely on [faraday](https://github.com/lostisland/faraday) under the hood.\nYou can use any of supported adapters (for example, `net/http/persistent`):\n\n```ruby\nrequire 'net/http/persistent'\n\nTelegram::Bot.configure do |config|\n  config.adapter = :net_http_persistent\nend\n```\n\n## Boilerplates\n\nIf you don't know how to setup database for your bot or how to use it with different languages\nhere are some boilerplates which can help you to start faster:\n\n- [Ruby Telegram Bot boilerplate](https://github.com/telegram-bots/ruby-telegram-bot-boilerplate)\n\n## Contributing\n\n1. Fork it.\n2. Create your feature branch (`git checkout -b my-new-feature`).\n3. Commit your changes (`git commit -am 'Add some feature'`).\n4. Push to the branch (`git push origin my-new-feature`).\n5. Create a new Pull Request.\n","funding_links":[],"categories":["Bot Libraries","Ruby","Telegram Libraries","Frameworks and libraries","Bots","一般机器人（bots）","Libraries"],"sub_categories":["Ruby","Telegram","Bot Libs","Unofficial","机器人类库"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatipugin%2Ftelegram-bot-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatipugin%2Ftelegram-bot-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatipugin%2Ftelegram-bot-ruby/lists"}