Volara Python SDK

The official Python client for the Volara API: messaging, conversations, CRM, broadcasts, knowledge search, metrics, and agency white-label. It has no third-party dependencies (standard library only) and runs on Python 3.9 and up.

Install

pip install volara

Authentication

Pass your API key directly, or set VOLARA_API_KEY and let the client pick it up:

from volara import Volara

client = Volara(api_key="sk_live_...")
# or, with VOLARA_API_KEY exported in the environment:
client = Volara()

Quickstart

Send your first WhatsApp message in four lines:

from volara import Volara

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

Examples

List and page through conversations:

# One page (with metadata when the API provides it)
result = client.conversations.list(status="open", per_page=25)
for conv in result["data"]:
    print(conv["id"], conv.get("status"))

# Or iterate every match without managing page numbers yourself
for conv in client.conversations.iterate(status="open"):
    print(conv["id"])

Create a contact:

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

Send a broadcast:

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

Search the knowledge base:

sources = client.knowledge.search("refund policy", scope="sources")
faqs = client.knowledge.search("shipping time", scope="faqs")

Read dashboard metrics:

metrics = client.metrics.dashboard()

Agency white-label (needs an agency-scoped key):

overview = client.agency.overview()
clients = client.agency.clients.list()
new_org = client.agency.clients.create_org(name="Acme Retail", slug="acme")

For anything the SDK doesn't model yet, use the escape hatch:

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

Verifying webhooks

Validate the HMAC-SHA256 signature on incoming webhooks. Always pass the raw request body — verifying a re-serialized JSON object will not match.

import os
from volara import verify_webhook

raw_body = request.get_data()  # bytes, not parsed JSON
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)

The signature header may be bare hex or prefixed with sha256=; both work.

Errors

Every failure raises a VolaraError (or a subclass), so you can catch them in one place. Use request_id when contacting support.

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 — the request exceeded the configured timeout.
• VolaraConnectionError — the request failed before a response (DNS, TLS, offline).

Resilience

The client retries 429 and 5xx responses (and network errors) with exponential backoff, honoring Retry-After. Write requests automatically carry an Idempotency-Key so retries are safe. Tune both at construction:

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

License

MIT