README.md

Viberroo

This Viber bot is a thin wrapper for Viber REST API, written in Ruby. It uses mostly the same parameters as the official API, and provides a more readable alternative to explicit http requests.

Installation

Add this line to your application's Gemfile:

gem 'viberroo', '~> 0.3.4'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install viberroo

Usage

First of all get acquainted with 'Getting Started' section on Viber REST API page. There you'll find a link to create a bot. Read about webhooks in the relevant section and come back here to setup one for yourself.

Webhooks

During webhook setup you need to specify an URL signed by known CA. NGrok is the tool to help in such predicament - here's a guide on how to get started.

Rake task is good way of managing webhooks:

$ rails g task viber set_webhook remove_webhook

  # lib/tasks/viber.rake
  namespace :viber do
    task set_webhook: :environment do
      Viberroo::Bot.new.set_webhook(
        url: 'https://<your_ngrok_public_address>/viber',
        event_types: %w[conversation_started subscribed unsubscribed],
        send_name: true,
        send_photo: true
      )
    end

    task remove_webhook: :environment do
      Viberroo::Bot.new.remove_webhook
    end
  end

We won't run our task just yet - during task execution API will make a callback request to our server to make sure it exists, and we'll need to handle that first. Also you'll need to provide your Viber API token:

# config/initializers/viberroo.rb

Viberroo.configure do |config|
  config.auth_token = '<your_viber_bot_api_token>'
end

Controller

Generate a controller with rails g controller viber callback and point a route to it:

# config/routes.rb

post '/viber' => 'viber#callback'

# app/controllers/viber_controller.rb

class ViberController < ApplicationController
  skip_before_action :verify_authenticity_token

  def callback
    @response = Viberroo::Response.new(params.permit!)
    @bot = Viberroo::Bot.new(response: @response)

    head :ok
  end
end

Note that params.permit! is necessary to form a correct Response object.

At this point running set_webhook task should return { "status":0, "status_message":"ok", ... }:

$ rake viber:set_webhook

From here we can fork the flow of execution based on event type as shown in handle_event method. For example when event type is 'message', we can fork the flow based on message text as shown in handle_message method. More information on callback events can be found in 'Callbacks' section in API Documentation

  # app/controllers/viber_controller.rb
  # ...

  def callback
    # ...
    handle_event

    head :ok
  end

  private

  def handle_event
    case @response.params.event
    when 'message'
      handle_message
    when 'conversation_started'
      greet_user
    end
  end

  def handle_message
    case @response.params.message.text
    when '/start'
      choose_action
    when '/help'
      display_help
    end
  end

  def greet_user
    message = Viberroo::Message.plain(text: 'Hello there! Type /start to get started.')
    @bot.send(message: message)
  end

To respond back to the user Viberroo::Bot class is equipped with send method which accepts various message types. See method name/message type mapping in documentation.

  # app/controllers/viber_controller.rb

  # ...

  def display_help
    message = Viberroo::Message.plain(text: 'Type /start to get started!')
    @bot.send(message: message)
  end

The Viber API allows sending a custom keyboard with predefined replies or actions. Such a keyboard can be attached to any message:

  # app/controllers/viber_controller.rb
  class ViberController < ApplicationController
    include Viberroo

    # ...

    def choose_action
      something = Input.reply_button({
        Columns: 3,
        Rows: 2,
        Text: 'Do Something',
        ActionBody: '/some_text_to_trigger_message_case'
      })

      google = Input.url_button({
        Columns: 3,
        Rows: 2,
        Text: 'Go to google',
        ActionBody: 'google.com'
      })

      message = Message.plain(text: 'What would you like to do?')
      keyboard = Input.keyboard(Buttons: [something, google])
      @bot.send(message: message, keyboard: keyboard)
    end
  end

Each buttons' ActionType has a corresponding method inside Viberroo::Input module. keyboard method also comes from there. See Viber API Button parameters section for parameter explanation and possibilities.

Documentation

Documentation can be found on rubygems, or generated locally by cloning the repository and running yard in the root of the project.

Development

After checking out the repository, run bin/setup to install dependencies. Then, run rspec 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, create a tag for a new version, and then merge to master, GitHub actions will take care of running specs and pushing to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/vikdotdev/viberroo.

License

The gem is available as open source under the terms of the MIT License.