telegram-bot Ruby Toolkit

The telegram-bot package provides a suite of tools for building Telegram bots, optimized for both Rails and standalone Ruby applications.

Core Components

• Lightweight Client: A thread-safe client for the Telegram Bot API using httpclient.
• Controller: A message parser that allows you to define methods for commands instead of using complex case statements.
• Middleware & Routes: Helpers designed for production environments (typically webhook-mode).
• Poller: A tool for development environments that includes an automatic source-reloader.
• Rake Tasks: Utilities to manage and update webhook URLs.
• Async Mode: Support for offloading work to a queue adapter to handle network errors gracefully.

Deployment Modes

• Development: Use poller-mode for local development.
• Production: Use webhook-mode for production environments, though poller-mode is also supported.

To maintain state between updates, include the Telegram::Bot::UpdatesController::Session module (or use the use_session! shortcut). Sessions use an ActiveSupport::Cache store.

Configuration

Set the store globally or per controller:

# Globally
Telegram::Bot::UpdatesController.session_store = :redis_store, {expires_in: 1.month}

# Per controller
MyController.session_store = :file_store

Customizing Session Keys

The default session ID is derived from the bot's username and (from || chat)['id']. To change this (e.g., to make a session unique to a specific user in a specific chat), override session_key.

class Telegram::WebhookController < Telegram::Bot::UpdatesController
  use_session!

  def write!(text = nil, *)
    session[:text] = text
  end

  def read!(*)
    respond_with :message, text: session[:text]
  end

  private

  # Custom key: session persists per user per chat
  def session_key
    "#{bot.username}:#{chat['id']}:#{from['id']}" if chat && from
  end
end

The UpdatesController allows you to organize bot logic into readable methods based on the type of update received (e.g., message, callback_query, inline_query). A new instance is created for every update, ensuring isolation.

Handling Update Types

Define methods with the same name as the update type. For common updates, parameters are passed directly. For others, use the payload method to access the full object.

Handling Commands

Define public methods ending with ! to handle commands. Arguments are parsed from the message and passed to the method. Use splat arguments (*args) to prevent errors if users provide unexpected argument counts.

Reply Helpers

Use these helpers within your controller to respond easily using the context of the current update:

• respond_with(type, params): Sets chat_id from the update.
• reply_with(type, params): Sets chat_id and reply_to_message_id.
• answer_inline_query(results, params = {})
• answer_callback_query(text, params = {})
• edit_message(type, params = {})

class Telegram::WebhookController < Telegram::Bot::UpdatesController
  # Handle a standard message
  def message(message)
    # logic here
  end

  # Handle a command like /start
  def start!(word = nil, *other_words)
    response = from ? "Hello #{from['username']}!" : 'Hi there!'
    respond_with :message, text: response
  end
end

For testing, use Telegram::Bot::ClientStub to prevent actual API calls. It stores requests in a requests hash for inspection.

Setup

Call Telegram::Bot::ClientStub.stub_all! before initializing any clients in your test environment.

Integration Testing

Depending on your environment, require the appropriate integration helper and tag your RSpec group:

• :rails: For Rails apps (requires rspec-rails).
• :rack: For non-Rails apps (requires rack-test).
• :poller: Calls .dispatch directly.

Example tag: RSpec.describe MyController, telegram_bot: :rails do ... end.

# spec/environments/test.rb
Telegram.reset_bots
Telegram::Bot::ClientStub.stub_all!

# spec/requests/telegram_webhooks_spec.rb
require 'telegram/bot/rspec/integration/rails'

RSpec.describe TelegramWebhooksController, telegram_bot: :rails do
  it 'shows usage of basic matchers' do
    # Verifies a sendMessage request was made
    expect { dispatch_command(:start) }.to make_telegram_request(bot, :sendMessage)
      .with(hash_including(text: 'msg text'))
  end
end