::TeBot

Welcome to yet another telegram bot webhook handler.

This gem is used to handle telegram webhook and sending message with telegram bot.

Installation

Install the gem and add to the application's Gemfile

gem 'te_bot'

Then run

bundle install    

If bundler is not being used to manage dependencies, install the gem by executing:

gem install te_bot

Usage

Webhook

This gem can be used as a standalone app since it implement rack interface. To use it as a standalone app, you need to define the webhook

# app.rb

require "te_bot"
require "te_bot/sender_options"

class MyWebhookApp < TeBot::Court
  access_token ENV["YOUR_BOT_ACCESS_TOKEN"]

  command("/start") do
    reply text: "Welcome aboard my friend!"
  end

  command("/today") do
    reply text: Time.now.to_s
  end
end

To run this as a standalone app, you need to install rack and a webserver such as puma

bundle add rack puma

create a file named config.ru as the rack entrypoint.

# config.ru

require_relative "./app"

run MyWebhookApp.new

To run the app we can use rackup

bundle exec rackup

For more detailed information about rack please visit Rack Repository.

Now, our MyWebhookApp class is ready to handle some commands from telegram bot which are /start and /today. The command aslo support argument that will be passed in the instance method params. To pass arguments, we can simply type /today city:Jakarta limit:10. The argument will be parsed as a Hash with string key => {"city" => "Jakarta", "limit" => "10"}.

To add a default handler for non existing command we can use the #default_command macro.

# app.rb

class MyWebhookApp < TeBot::Court
  default_command do
    reply text: "Sorry, Comand not found. Try another command. or type /help"
  end
end

All the messages are passed in the instance method message

Other type of messages are also supported by using this macros text for regular text message, query, document, audio, and voice. For more detail please check this Telegram Docs.

# app.rb

class MyWebhookApp < TeBot::Court
  text do
    reply_message = do_some_fancy_stuff_here(message)
    reply text: reply_message
  end
end

And also we can define a macro for default action #default_action if the request does not match with this Documentation, Or we have not created the handler for that specific message type.

# app.rb

class MyWebhookApp < TeBot::Court
  default_action do
    reply text: "No, I can't talk like people. use command instead"
  end
end

Since this app implements rack interface, and rails is also a rack based application. We can mount this app direcly inside rails app.

# config/routes.rb

require "lib/to/your_webhook"

Rails.application.routes.draw do
  mount MyAwessomWebhook.new => "telegram_webhook"
end

Sending Message to Telegram

To send message direcly to telegram, we can use this module TeBot::Wire and need to require "te_bot/sender_options" to add default handler for different type of messages. Available message types are :text, :markdown, :photo, :audio, :document, :video, :animation amd :voice

Some supported message by default:

# app.rb
sender = TeBot::Wire.new(ENV['YOUR_ACCESS_TOKEN_HERE'])
sender.send_message(chat_id, text: message_string)
sender.send_message(chat_id, markdown: markdown_string)

sender.send_message(chat_id, photo: { photo: url, caption: caption })
sender.send_message(chat_id, video: { video: url, caption: caption})
sender.send_message(chat_id, document: { document: url, caption: caption})
sender.send_message(chat_id, audio: { audio: url, caption: caption})
sender.send_message(chat_id, animation: { animation: url, caption: caption})

For markdown telegram supports MarkdownV2 refer to this Please check the documentation for more details.

Custom Handler

Of course you can add more handler by extending the TeBot::Wire class

# in/your/custom_handler.rb

TeBot::Wire.class_eval do
  sender :json do |chat_id, message|
    make_request("sendMessage", body: { chat_id: chat_id, json: message }.to_json)
  end
end

Helpers

Using module

# request_helpers.rb

module RequestHelpers
  def get_nearest_hospitals
    # do some fancy stuff
  end

  def get_the_nearest_routes(hospitals)
    # do some even fancier stuff
  end 

  def render_markdown(routes)
    # do something else
  end
end

class MyWebhookApp < TeBot::Court
  include RequestHelpers

  #... the rest of the code
end

Using instance methods

# app.rb

class MyWebhookApp < TeBot::Court
  command("/findhospital") do
    hospitals = get_nearest_hospitals(params)
    routes = get_the_nearest_routes(hospitals)

    reply markdown: render_markdown(routes)
  end

  def get_nearest_hospitals(data)
    # do some fancy stuff
  end

  def get_the_nearest_routes(hospitals)
    # do some even fancier stuff
  end 

  def render_markdown(routes)
    # do something else
  end
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/aaripurna/te_bot. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Code of Conduct

Everyone interacting in the TeBot project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.