ChatAja Bot

Bot merupakan aplikasi yang berjalan dalam ChatAja. Pengguna dapat berinteraksi dengan bot dengan cara mengirim suatu pesan atau perintah ke bot dan bot tersebut dapat menjalankan suatu aksi berdasarkan input. Bot juga dapat mengirimkan pesan secara otomatis ke pengguna. ChatBot Builder merupakan bot yang digunakan untuk mengelola bot-bot milik seorang pengguna.

Command ChatBot Builder

/createbot – Membuat akun Bot baru
/editbot – Mengubah informasi dan atribut dari bot yang dipilih
/listbot – Menampilkan daftar bot yang dibuat beserta informasi/atributnya
/deletebot – Menghapus bot yang telah dibuat
/bantuan – Menampilkan perintah-perintah yang dapat dijalankan ChatBot Builder
/batal – Keluar dari menu perintah yang sedang dijalankan

Pembuatan Bot

Untuk membuat akun bot baru, add ChatBot Builder dari halaman Discover, lalu masukkan perintah /createbot. ChatBot Builder akan meminta anda untuk memasukkan informasi terkait bot yang anda buat, seperti username, full name, password, deskripsi, dan profile picture.

Username dan password digunakan oleh pengguna untuk mencari dan add bot anda dari halaman Discover.

Full name, deskripsi, dan profile picture yang anda masukkan akan ditampilkan sebagai contact detail dari bot yang dibuat.

Setelah ChatBot Builder menerima informasi yang diperlukan dari bot yang dibuat, ChatBot Builder akan membuat dan memberikan informasi access token baru dari bot yang dibuat. Access token tersebut digunakan dalam membangun API Bot dan url API tersebut dapat dihubungkan ke webhook bot tersebut dengan memasukkan perintah /editbot.

Untuk melihat informasi yang sudah dibuat, masukkan perintah /listbot dan pilih bot yang sudah dibuat

Edit Bot

/edit_fullname – Mengubah nama profile bot
/edit_password – Mengubah password untuk add bot
/edit_access_token – Membuat akses token baru
/edit_description – Mengubah deskripsi profile bot
/edit_webhook – Mengubah webhook yang terhubung ke bot
/edit_photo – Mengubah profile picture bot

API Bot

Pembuatan API Bot ChatAja dapat mengikuti kode sample yang sudah ada, yaitu sample dalam tiga bahasa berikut.

Kode yang dapat diubah terkait input dan output bot adalah kode chatcontroller. Bagian yang dapat diubah adalah metode run dan metode lainnya yang dipanggil dari metode run tersebut. Run menerima input dari user dan menentukan output bot.

Terdapat lima tipe output dari bot, yaitu Text, Button, Card, Location, dan Carousel. Sample telah memberikan contoh metode-memberikan yang memberikan output dalam masing-masing tipe tersebut. Untuk mengubah isi output, nilai payload pada masing-masing metode dapat diubah.

Agar API dapat mengakses suatu data, dapat dihubungkan ke basis data atau dibuat tabel baru, dan dibuat sebuah model untuk mengakses basis data. Untuk menghubungkan API dengan bot, edit webhook bot dan isi dengan url API tersebut. URL API bisa didapatkan dengan menggunakan ngrok untuk API yang dijalankan di localhost, atau dengan me-deploy API tersebut.

Contoh Implementasi Bot ChatAja Menggunakan Ruby

Requirement:

Ruby https://www.ruby-lang.org/en/ → bahasa program
Ruby on Rails https://rubyonrails.org/ → framework ruby untuk web development
Bundler https://bundler.io/bundle_install.html → Ruby depedensi manajemen
Ngrok https://ngrok.com/ → http tunneling

Pertama buat project rails pada direktori yang diinginkan melalui cmd/terminal dengan nama sample-bot-chataja
$ cd <directory path>

$ rails new sample-bot-chataja --skip-turbolinks --skip-spring --skip-test
                  --skip-bundle

$ cd sample-bot-chataja

Kemudian buka file Gemfile, tambahkan depedensi unirest seperti di bawah ini:

gem 'unirest'

library HTTP → http://unirest.io/ruby.html

Setelah itu kembali ke cmd/terminal jalankan command dibawah ini:
$ bundle install
Depedensi akan terinstall

Sebelum membuat class Model, kita perlu tahu response data dari callback url webhook agar dapat menentukan atribut dan parameter apa saja yang dibutuhkan. Di bawah ini merupakan contoh response yang dihasilkan dari webhook ChatAja engine:

{
    "callback_url": "https:\/\/56f5d7ab.ngrok.io",
    "token": "asasdasd",
    "api_base_url": "http:\/\/api.chataja.co.id",
    "type": "post_comment_mobile",
    "from": {
        "id": 462123,
        "phone_number": "+6282222222",
        "fullname": "Iskandar Suhaimi",
        "qiscus_email": "userid_123122@chataja-prod.com",
        "qiscus_id": 21231231
    },
    "my_account": {
        "id": 461231,
        "phone_number": "+628211111",
        "fullname": "Telkom ChatAja",
        "qiscus_email": "userid_12312312@chataja-prod.com"
    },
    "chat_room": {
        "id": 3812312,
        "qiscus_room_name": "Group Chat Name",
        "qiscus_room_id": 2112312,
        "is_group_chat": false,
        "created_at": "2019-03-25T03:53:34.930Z",
        "updated_at": "2019-03-25T03:53:34.930Z",
        "application_id": 3,
        "group_avatar_url": "",
        "is_official_chat": false,
        "target_user_id": 412312,
        "is_public_chat": false,
        "is_channel": false,
        "users": [
            {
                "id": 412312,
                "phone_number": "+628222222",
                "fullname": "Iskandar Suhaimi",
                "qiscus_email": "userid_1231231@chataja-prod.com",
                "qiscus_id": 212312312
            },
            {
                "id": 4123123,
                "phone_number": "+62821111",
                "fullname": "Telkom ChatAja",
                "qiscus_email": "userid_12312312@chataja-prod.com",
                "qiscus_id": 212312312
            }
        ],
        "chat_name": "Group Chat Name",
        "chat_avatar_url": ""
    },
    "message": {
        "payload": [],
        "text": "halo",
        "type": "text"
    }
}

Dari response di atas, kita membutuhkan parameter:

chat_room → id untuk mengetahui dimana bot berinteraksi dengan user
message → text untuk mengetahui konten pesan yang dikirim ke bot
message → type untuk mengetahui jenis pesan yang dikirim ke bot
from → fullname untuk mengetahui siapa nama pengirim pesan tersebut

Kemudian kembali ke cmd/terminal, buat model baru pada project dengan nama Chat seperti command di bawah ini
$ rails generate model Chat

Lalu buka file \app\models\chat.rb , tambahkan atribut-atribut yang dibutuhkan seperti di bawah ini:

class Chat 
    include ActiveModel::Model  #set agar model di rails bisa jalan sesuai kebutuhan
    attr_reader :room_id, :message, :message_type, :sender #set atribut model untuk menampung response data chat   
end

Setelah itu tambahkan constructor untuk inisiasi data di dalam class Model

def initialize(room_id, message, message_type, sender)
    @room_id = room_id
    @message = message
    @message_type = message_type
    @sender = sender
end

Setelah itu kembali ke cmd/terminal, buat controller baru pada project dengan nama Chat seperti command di bawah ini
$ rails generate controller Chat

Lalu buka file \app\controllers\chat_controller.rb kemudian buat atribut yang dibutuhkan untuk class Controller

require 'unirest' #panggil depedensi unirest

class ChatController < ApplicationController
    skip_before_action :verify_authenticity_token #skip verify token rails
    attr_accessor :apiResponse, :access_token, :apiurl, :headers #set-get atribut controller
end

Setelah itu tambahkan constructor untuk inisiasi data atribut di dalam class Controller

#inisiasi nilai atribut
def initialize()
    @access_token = '<input akses token disini>'
    @apiurl = 'https://api.chataja.co.id/api/v1/chat/conversations/'
    @headers = { 
        'Content-Type' => 'application/json'
    }
end

Copy access token yang didapat dari ChatBot Builder saat bot berhasil dibuat dan paste access token tersebut ke Controller

Setelah itu tambahkan method yang berfungsi untuk mengambil dan menampung response data dari webhook di dalam Controller

#ambil dan tampung response data dari webhook
def getResponse
    if request.headers['Content-Type'] == 'application/json'
        self.apiResponse = JSON.parse(request.body.read)
    else
        #application/x-www-form-urlencoded
        self.apiResponse = params.as_json
    end

    #siapkan log untuk memastikan data terambil
    File.open('log-comment.txt','w') do |f|
        f.write(JSON.pretty_generate(self.apiResponse))
    end 
end

Lalu tambahkan method yang berfungsi untuk melaksanakan command bot di dalam Controller dengan memanfaatkan API post-comment ChatAja

Post-comment Button

#contoh penggunaan api post-comment untuk jenis button
def replyCommandButton(display_name, room_id)
    comment = 'Halo, '+display_name+' ini adalah contoh payload button yang bisa kamu coba'
    payload = {
        'text' => comment,
        'buttons' => [
            {
                'label' => 'Tombol Reply Text',
                'type' => 'postback',
                'payload' => {
                    'url' => '#',
                    'method' => 'get',
                    'payload' => 'null'
                }
            },
            {
                'label' => 'Tombol Link',
                'type' => 'link',
                'payload' => {
                    'url' => 'https://www.google.com',
                }
            }
        }
    }
    replay = { 
        'access_token' => self.access_token,
        'topic_id' => room_id,
        'type' => 'buttons',
        'payload' => payload.to_json
    }
    post_comment = Unirest.post(self.apiurl+'post_comment', headers: self.headers, parameters: replay)
    render :json => post_comment.raw_body
end

Post-comment Text

#contoh penggunaan api post-comment untuk jenis text
def replyCommandText(display_name, message_type, room_id)
    comment = 
    'Maaf '+display_name+', command yang kamu ketik salah. Jenis pesan kamu adalah '+message_type+'. Silahkan coba command berikut : '+
    '/location, /button, /card, /carousel'

    replay = {
        'access_token' => self.access_token,
        'topic_id' => room_id,
        'type' => 'text',
        'comment' => comment
    }
    post_comment = Unirest.post(self.apiurl+'post_comment', headers: self.headers, parameters: replay)
    render :json => post_comment.raw_body
end

Post-comment Location

#contoh penggunaan api post-comment untuk jenis location
def replyCommandLocation(room_id)
    payload = {
        'name' => 'Telkom Landmark Tower',
        'address' => 'Jalan Jenderal Gatot Subroto No.Kav. 52, West Kuningan, Mampang Prapatan, South Jakarta City, Jakarta 12710',
        'latitude' => '-6.2303817',
        'longitude' => '106.8159363',
        'map_url' => 'https://www.google.com/maps/@-6.2303817,106.8159363,17z'
    }
    replay = {
        'access_token' => self.access_token,
        'topic_id' => room_id,
        'type' => 'location',
        'payload' => payload.to_json
    }
    location  = Unirest.post(self.apiurl+'post_comment', headers: self.headers, parameters: replay);
    render :json => location.raw_body
end

Post-comment Carousel

#contoh penggunaan api post-comment untuk jenis carousel
def replyCommandCarousel(room_id)
    payload = {
        'cards' => [
            {
                'image' => 'https://cdns.img.com/a.jpg',
                'title' => 'Gambar 1',
                'description' => 'Carousel Double Button',
                'default_action' => {
                    'type' => 'postback',
                    'postback_text' => 'Load More...',
                    'payload' => {
                        'url' => 'https://j.id',
                        'method' => 'GET',
                        'payload'=> nil
                    }
                },
                'buttons' => [
                    {
                        'label' => 'Button 1',
                        'type' => 'postback',
                        'postback_text' => 'Load More...',
                        'payload' => {
                            'url' => 'https://www.r.com',
                            'method' => 'GET',
                            'payload' => nil
                        }
                    },
                    {
                        'label' => 'Button 2',
                        'type' => 'postback',
                        'postback_text' => 'Load More...',
                        'payload' => {
                            'url' => 'https://www.r.com',
                            'method' => 'GET',
                            'payload' => nil
                        }
                    }
                ]
            },
            {
                'image' => 'https://res.cloudinary.com/hgk8.jpg',
                'title' => 'Gambar 2',
                'description' => 'Carousel single button',
                'default_action' => {
                    'type' => 'postback',
                    'postback_text' => 'Load More...',
                    'payload' => {
                        'url' => 'https://j.id',
                        'method' => 'GET',
                        'payload'=> nil
                    }
                },
                'buttons' => [
                    {
                        'label' => 'Button 1',
                        'type' => 'postback',
                        'postback_text' => 'Load More...',
                        'payload' => {
                            'url' => 'https://www.r.com',
                            'method' => 'GET',
                            'payload' => nil
                        }
                    }
                ]
            }
        ]
    }
    replay = {
        'access_token' => self.access_token,
        'topic_id' => room_id,
        'type' => 'carousel',
        'payload' => payload.to_json
    }
    carousel = Unirest.post(self.apiurl+'post_comment', headers: self.headers, parameters: replay);
    render :json => carousel.raw_body
end

Post-comment Card

#contoh penggunaan api post-comment untuk jenis card
def replyCommandCard(room_id)
    payload = {
        'text' => 'Special deal buat sista nih..',
        'image' => 'https://cdns.img.com/a.jpg',
        'title' => 'Gambar 1',
        'description' => 'Card Double Button',
        'url' => 'http://url.com/baju?id=123%26track_from_chat_room=123',
        'buttons' => [
            {
                'label' => 'Button 1',
                'type' => 'postback',
                'postback_text' => 'Load More...',
                'payload' => {
                    'url' => 'https://www.r.com',
                    'method' => 'GET',
                    'payload' => nil
                }
            },
            {
                'label' => 'Button 2',
                'type' => 'postback',
                'postback_text' => 'Load More...',
                'payload' => {
                    'url' => 'https://www.r.com',
                    'method' => 'GET',
                    'payload' => nil
                }
            }
        ]
    }
    replay = {
        'access_token' => self.access_token,
        'topic_id' => room_id,
        'type' => 'card',
        'payload' => payload.to_json
    }
    card  = Unirest.post(self.apiurl+'post_comment', headers: self.headers, parameters: replay);
    render :json => card.raw_body
end

Kemudian tambahkan method run pada Controller yang berguna untuk menjalankan bot dan mengarahkan command message sesuai dengan fungsi-fungsi yang sudah dibuat sebelumnya (method-method reply command di atas). Ikuti code di bawah ini

#fungsi untuk jalankan bot
def run
    self.getResponse 
    chat = Chat.new(
        self.apiResponse['chat_room']['qiscus_room_id'],
        self.apiResponse['message']['text'],
        self.apiResponse['message']['type'],
        self.apiResponse['from']['fullname']
    )

    #cek pesan dari chat tidak kosong & cari chat yang mengandung '/' untuk menjalankan command bot
    find_slash = chat.message.scan('/')
    if chat.message != nil && find_slash[0] == '/'
        #ambil nilai text setelah karakter '/'
        command = chat.message.split('/')
        if command[1] != nil
            case command[1]
                when 'location'
                    self.replyCommandLocation(chat.room_id)
                when 'carousel'
                    self.replyCommandCarousel(chat.room_id)
                when 'button'
                    self.replyCommandButton(chat.sender, chat.room_id)
                when 'card'
                    self.replyCommandCard(chat.room_id)
                else
                    self.replyCommandText(chat.sender, chat.message_type, chat.room_id)            
            end
        else
            self.replyCommandText(chat.sender, chat.message_type, chat.room_id)
        end
    end
end

Setelah itu buka file config\routes.rb, tambahkan code untuk memanggil Controller dan method run yang menjalankan program di url root ('/') localhost:3000

Rails.application.routes.draw do
  post '/' => 'chat#run', as: "receive_webhooks"
end

Lalu kembali ke cmd/terminal jalankan program yang telah dibuat
$ rake db:create db:migrate
$ rails server

Kemudian jalankan http tunneling dengan Ngrok untuk mendapatkan link https yang menjalankan http local pada port 3000. Link forward ini akan di daftarkan nanti melalui ChatBot Builder sebagai webhook callback url-nya
$ ngrok http 3000

Setelah itu edit webhook melalui ChatBot Builder dan copy-paste link ini https://131464b2.ngrok.io

Selesai, sample bot ChatAja siap dicoba