Volara Docs

Tema

SDK Ruby ​

volara adalah klien resmi Ruby untuk Volara. Kirim pesan WhatsApp dan omnichannel, kelola conversations dan contacts, jalankan broadcast, cari knowledge base, baca metrics, dan provision org klien agency.

Dibangun di atas standard library Ruby — tanpa gem runtime untuk dipasang. Jalan di Ruby 3.0+.

Kode sumber: github.com/volara-asia.

Install ​

bash
gem install volara

Atau tambahkan ke Gemfile:

ruby
gem "volara"

Autentikasi ​

Ambil API key dari dashboard Volara (Settings → API Keys). Berikan langsung, atau set env VOLARA_API_KEY dan biarkan klien membacanya.

ruby
client = Volara::Client.new(api_key: "sk_live_...")
# atau, dengan VOLARA_API_KEY di environment:
client = Volara::Client.new

Jaga kerahasiaan API key

API key memberi akses penuh ke data tenant. Pakai hanya dari server, jangan menaruhnya di kode klien atau repo publik.

Quickstart — kirim pesan pertama ​

ruby
require "volara"

client = Volara::Client.new            # membaca VOLARA_API_KEY
message = client.messages.send("conv_123", text: "Halo dari Ruby!")
puts message[:id]

Contoh resource ​

Respons kembali sebagai hash dengan symbol key (mis. message[:id]). Endpoint list mengembalikan { data: [...], total:, page:, limit: } saat API menyertakan metadata.

ruby
# Conversations
client.conversations.list(status: "open", per_page: 25)[:data].each do |conv|
  puts conv[:id]
end

# Iterasi semua percakapan tanpa mengelola offset
client.conversations.each { |conv| puts conv[:id] }

# Ambil satu percakapan
client.conversations.get("conv_123")

# Contacts (CRM, telepon dalam E.164)
client.contacts.create(name: "Sari", phone_number: "+6281234567890", source: "website")

# Broadcasts
client.broadcasts.create(title: "Promo Lebaran", message_content: "Diskon 20% hari ini!")

# Knowledge base & metrics
client.knowledge.search("refund policy", scope: "faqs")
client.metrics.dashboard

Escape hatch ​

ruby
client.request("/tickets", query: { status: "open" })

Verifikasi webhook ​

Verifikasi tanda tangan terhadap body mentah sebelum mempercayai event. Header boleh hex polos atau membawa awalan sha256= — keduanya diterima, dan perbandingannya constant-time.

ruby
ok = Volara::Webhooks.verify(
  payload: raw_request_body,
  signature: request.get_header("HTTP_X_VOLARA_SIGNATURE").to_s,
  secret: ENV.fetch("VOLARA_WEBHOOK_SECRET")
)

Contoh di Sinatra:

ruby
post "/webhooks/volara" do
  raw = request.body.read
  sig = request.env["HTTP_X_VOLARA_SIGNATURE"].to_s
  halt 401 unless Volara::Webhooks.verify(
    payload: raw, signature: sig, secret: ENV.fetch("VOLARA_WEBHOOK_SECRET")
  )
  event = JSON.parse(raw)
  # tangani event...
  status 200
end

Error handling ​

Setiap respons non-2xx, plus kegagalan jaringan dan timeout, memunculkan Volara::Error. Timeout dan kegagalan koneksi memakai subclass Volara::TimeoutError dan Volara::ConnectionError, jadi cukup tangkap base class untuk semuanya.

ruby
begin
  client.conversations.get("missing")
rescue Volara::Error => err
  warn err.message      # human-readable
  warn err.status       # status HTTP (0 untuk jaringan/timeout)
  warn err.code         # kode mesin, mis. "VLR-..."
  warn err.request_id   # kutip ini saat menghubungi support
end

Resilience ​

  • Retry otomatis dengan exponential backoff pada 408, 425, 429, dan 5xx, plus error jaringan sementara. Retry-After dihormati bila ada.
  • Timeout per-permintaan (timeout:, default 30 detik) dan budget retry (max_retries:, default 2) yang bisa dikonfigurasi.
  • Idempotency-Key dibuat otomatis untuk setiap operasi tulis. Berikan milik Anda dengan idempotency_key:.
ruby
client = Volara::Client.new(timeout: 10, max_retries: 4)

Langkah selanjutnya ​