Volara Docs

Tema

SDK Python ​

volara adalah klien resmi Python untuk Volara: messaging, conversations, CRM, broadcast, knowledge search, metrics, dan agency white-label. Tanpa dependensi pihak ketiga (standard library saja) dan jalan di Python 3.9 ke atas.

Kode sumber: github.com/volara-asia.

Install ​

bash
pip install volara

Autentikasi ​

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

python
from volara import Volara

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

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 ​

python
from volara import Volara

client = Volara()  # membaca VOLARA_API_KEY
message = client.messages.send("conv_123", text="Halo dari Volara!")
print(message["id"])

Contoh resource ​

Conversations ​

python
# Satu halaman (dengan metadata bila API menyediakannya)
result = client.conversations.list(status="open", per_page=25)
for conv in result["data"]:
    print(conv["id"], conv.get("status"))

# Atau iterasi semua tanpa mengelola nomor halaman sendiri
for conv in client.conversations.iterate(status="open"):
    print(conv["id"])

Contacts (CRM) ​

python
contact = client.contacts.create(
    name="Sita Dewi",
    phone_number="+6281234567890",
    email="sita@example.com",
)

Broadcasts ​

python
broadcast = client.broadcasts.create(
    title="Promo Akhir Pekan",
    message_content="Diskon 20% akhir pekan ini!",
)

Knowledge base & metrics ​

python
sources = client.knowledge.search("refund policy", scope="sources")
faqs = client.knowledge.search("estimasi pengiriman", scope="faqs")
metrics = client.metrics.dashboard()

Escape hatch ​

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

Verifikasi webhook ​

Validasi tanda tangan HMAC-SHA256 pada webhook masuk. Selalu pakai body mentah — memverifikasi JSON yang sudah di-serialize ulang tidak akan cocok.

python
import os, json
from volara import verify_webhook

raw_body = request.get_data()  # bytes, bukan JSON yang sudah di-parse
signature = request.headers.get("x-volara-signature", "")

if not verify_webhook(raw_body, signature, os.environ["VOLARA_WEBHOOK_SECRET"]):
    abort(401)

event = json.loads(raw_body)

Header tanda tangan boleh hex polos atau berawalan sha256=; keduanya diterima.

Error handling ​

Setiap kegagalan memunculkan VolaraError (atau subclass-nya), jadi bisa ditangkap di satu tempat. Pakai request_id saat menghubungi support.

python
from volara import Volara, VolaraError

client = Volara()
try:
    client.conversations.get("does-not-exist")
except VolaraError as err:
    print(err.status, err.code, err.request_id, err.message)
  • VolaraTimeoutError — permintaan melebihi timeout yang dikonfigurasi.
  • VolaraConnectionError — permintaan gagal sebelum ada respons (DNS, TLS, offline).

Resilience ​

Klien me-retry respons 429 dan 5xx (serta error jaringan) dengan exponential backoff, menghormati Retry-After. Setiap operasi tulis otomatis membawa Idempotency-Key agar retry aman. Atur keduanya saat membuat klien:

python
client = Volara(timeout=15, max_retries=3, base_url="https://api.volara.chat")

Langkah selanjutnya ​