volga-sdk 1.0.0

Official Python SDK for the Volga Public API (conversations, messages, outbound webhooks).

volga

Official Python SDK for the Volga Public API — conversations, messages, and outbound webhooks.

• Zero dependencies (standard library only)
• Automatic retries (429 + 5xx + network) with Retry-After support
• Cursor auto-pagination via generators
• Built-in webhook signature verification
• Python 3.8+

Install

pip install volga-sdk

(The distribution is volga-sdk; you still import volga.)

Quickstart

import os
from volga import VolgaClient

volga = VolgaClient(api_key=os.environ["VOLGA_API_KEY"])

# List conversations
page = volga.conversations.list(channel="whatsapp", limit=25)

# Send a reply (idempotent retries)
import uuid
volga.messages.send(
    conversation_id=page["data"][0]["id"],
    text="Thanks for reaching out!",
    idempotency_key=str(uuid.uuid4()),
)

Pagination

# One page at a time
page = volga.messages.list(conversation_id="c_123")
print(page["data"], page["has_more"], page["next_cursor"])

# Or auto-paginate every item
for message in volga.messages.iterate(conversation_id="c_123"):
    print(message["id"], message["text"])

Webhooks

Register an endpoint (the signing secret is returned once):

endpoint = volga.webhook_endpoints.create(
    url="https://example.com/volga/webhooks",
    event_types=["message.received", "conversation.created"],
)
# store endpoint["secret"] securely

Verify and parse incoming deliveries (pass the raw request body):

from volga import construct_event, VolgaSignatureVerificationError

@app.post("/volga/webhooks")
def handle(request):
    try:
        event = construct_event(
            secret=os.environ["VOLGA_WEBHOOK_SECRET"],
            payload=request.get_data(),  # raw bytes, not parsed JSON
            signature_header=request.headers.get("Volga-Signature"),
        )
    except VolgaSignatureVerificationError:
        return "", 400
    # handle event["type"] / event["data"] ...
    return "", 200

Deliveries are at-least-once — deduplicate on the event id (or the Volga-Delivery-Id header).

Errors

from volga import VolgaRateLimitError, VolgaPermissionError, VolgaApiError

try:
    volga.messages.send(conversation_id=cid, text=text)
except VolgaRateLimitError as e:
    time.sleep(e.retry_after_sec or 1)
except VolgaPermissionError:
    ...  # the key is missing a scope
except VolgaApiError as e:
    print(e.status, e.code, e.message, e.trace_id)

Class	Status
VolgaInvalidRequestError	400 / 422
VolgaAuthenticationError	401
VolgaPaymentRequiredError	402
VolgaPermissionError	403
VolgaNotFoundError	404
VolgaConflictError	409
VolgaRateLimitError	429
VolgaServerError	5xx
VolgaConnectionError / VolgaTimeoutError	no response

Configuration

VolgaClient(
    api_key="vk_live_…",
    base_url="https://hooks.volga-ai.com/v1",  # default
    timeout=30.0,        # default
    max_retries=2,       # default
    retry_base_delay=0.5,
    retry_max_delay=8.0,
)

License

MIT