qiscus

Zero-dependency Ruby client for the Qiscus Omnichannel (Qismo) HTTP API.

Apa itu Qiscus?

Qiscus Omnichannel (Qismo) adalah platform customer engagement yang menyatukan banyak channel — WhatsApp, Instagram, web chat, dll — ke dalam satu inbox, lengkap dengan agent, bot, broadcast, dan webhook. Semua fitur itu diakses lewat HTTP API.

Kenapa pakai gem ini?

• Zero dependency — cuma net/http + json dari stdlib. Tidak menambah beban dependency atau risiko konflik versi di project kamu.
• Tidak perlu hafal endpoint — wrapper Ruby yang rapi (client.room.tag(...)) menggantikan URL, header auth, dan pagination yang harus diurus manual.
• Auth otomatis — tiap method tahu header mana yang dipakai (default / admin / bot / SDK), kamu tinggal kasih kredensial sekali di awal.
• Pagination otomatis — helper seperti agent.all dan comment.load_by_room mengambil semua halaman untukmu.
• Error sebagai exception — status >= 400 jadi Qiscus::Omnichannel::Error yang bisa di-rescue, bukan hash yang harus dicek manual.

Install

# Gemfile
gem "qiscus", git: "https://github.com/Qiscus-Integration/qiscus-gem.git", tag: "v0.1.0"

Configure (optional)

Default sudah menunjuk ke production Qiscus, jadi blok ini cuma perlu kalau mau ganti host (mis. staging / dedicated instance) atau pasang logger.

Qiscus::Omnichannel.configure do |c|
  c.base_url = "https://multichannel-api.qiscus.com" # default
  c.sdk_url  = "https://api.qiscus.com"              # default
  c.logger   = Rails.logger                          # default: no-op
end

Custom URL

Ada dua host: base_url (endpoint Omnichannel) dan sdk_url (endpoint SDK, dipakai comment.load_by_room & sdk.upload_from_url). Bisa di-override secara global (untuk semua client) lewat configure di atas, atau per-client saat init:

client = Qiscus::Omnichannel::Client.new(
  app_code:   ENV.fetch("QISCUS_APP_CODE"),
  app_secret: ENV.fetch("QISCUS_APP_SECRET"),
  base_url:   "https://multichannel-api.staging.qiscus.com", # override base
  sdk_url:    "https://api.staging.qiscus.com"               # override sdk
)

Argumen base_url/sdk_url di Client.new menang atas konfigurasi global. Yang tidak diisi akan jatuh ke nilai global / default.

Use

client = Qiscus::Omnichannel::Client.new(
  app_code:    "xxx",
  app_secret:  "yyy",
  admin_token: "zzz" # optional, for admin endpoints
)

client.room.resolved(room_id, "handled")
client.bot.send_message("hello", room_id)
client.broadcast.list_templates           # => Array
client.agent.all                          # => Array (paginated)
client.login_admin("admin@example.com", "secret") # => full parsed body hash

begin
  client.room.tag(room_id, "vip")
rescue Qiscus::Omnichannel::Error => e
  e.status # => Integer
  e.body   # => String
end

Use cases

# Ambil room + semua comment-nya
customer = client.room.customer(room_id)        # => Hash data customer
comments = client.comment.load_by_room(room_id) # => Array (auto-paginate)

# Custom agent allocation: pilih agent available, fallback ke auto-allocate
available = client.agent.available(room_id)     # butuh admin_token
if available.empty?
  client.room.allocate_agent(room_id)           # auto-allocate bawaan Qiscus
else
  client.room.assign_agent(available.first["id"], room_id)
end
client.room.activate_bot(room_id, false)        # handover: matikan bot
client.room.tag(room_id, "vip")

# Kirim WhatsApp & broadcast
client.whatsapp.send_text("628123456789", "Pesananmu dikirim 📦", channel_id)
client.broadcast.list_templates                 # => Array template HSM approved

Resources

room bot agent comment contact broadcast whatsapp config channel sdk helper

Methods return the full parsed JSON hash, except the named collection helpers (agent.all, agent.available, channel.wa_channels, broadcast.list_templates, comment.load_by_room, room.customer, sdk.upload_from_url).

Detail lengkap, error handling, dan use case custom agent allocation: docs/usage.md.

Testing

Method gem ini ujungnya memanggil HTTP (net/http). Di unit test, stub lapisan HTTP-nya — jangan hit API asli:

require "webmock/minitest" # atau webmock/rspec

stub_request(:get, "https://multichannel-api.qiscus.com/api/v2/customer_rooms")
  .to_return(status: 200, body: { data: { customer_rooms: [] } }.to_json)

client = Qiscus::Omnichannel::Client.new(app_id: "x", app_secret: "y", admin_token: "z")
client.room.list # kebaca stub, tidak ke internet

Turn a Rails app into a Qiscus Omnichannel addon

The gem ships a generator that scaffolds the AppCenter lifecycle (register / status / setting / unregister), the Omnichannel model, routes, iframe + session config, and JWT login into a host Rails app.

# Gemfile
gem "qiscus", git: "https://github.com/Qiscus-Integration/qiscus-gem.git", tag: "v0.1.0"
gem "jwt"

bundle install
rails g qiscus:addon
rails db:migrate

Then set:

QISCUS_ADDON_JWT   # shared AppCenter JWT secret (HS256)
QISCUS_BASE_URL    # optional; defaults to https://multichannel-api.qiscus.com

The generated Omnichannel model exposes #client, so any controller can call the API:

class TicketsController < ApplicationController
  before_action :authenticate_user   # provided by the generated Qiscus::AddonAuthentication concern

  def resolve
    @current_app.client.room.resolved(params[:room_id], "handled")
  end
end

See docs/addon.md for what the generator creates and how to customize it.