VoiFlow for Python

Run your voice agents from your own backend: create businesses, set up agents, start calls, read transcripts and get webhooks.

pip install voiflow

Python 3.9 or newer, no other packages needed. The client is synchronous and returns plain dicts.

Quickstart

import os
from voiflow import VoiFlowClient

client = VoiFlowClient(api_key=os.environ["VOIFLOW_API_KEY"])

for business in client.businesses.list():
    print(business["id"], business["name"])

call = client.calls.create(
    {"agent_id": "agent_id", "contact_id": "contact_id", "mission": "Confirm tomorrow's visit"},
    business_id="business_id",  # only needed if your key covers more than one business
)
print(call["call_id"], call["status"])  # "starting": the call is accepted, not yet connected

Keys

Create keys in the Partner Portal under Developers. A vf_test_ key works on test data and never places a real call or touches a live business. A vf_live_ key acts on real businesses and real customers. Both are secret: keep them on your server and give browsers a short-lived token from client.sessions.create instead.

A key is either tied to one business or can manage all of yours. With a management key, pass business_id on each call (or create the business first with businesses.create).

Lists

List methods return an iterator and fetch the next page for you.

for call in client.calls.list(days="7"):
    print(call["call_id"])

Errors and retries

Failures raise VoiFlowError with status, code, message, request_id and details. A network failure or an HTTP 202 means the result is not known yet (VoiFlowConnectionError, VoiFlowOperationPending): do not start the action again under a new key. Every method that changes something takes idempotency_key; if you leave it out, one is generated and reused on automatic retries, and it is on the error as err.idempotency_key so you can retry the same action safely.

Webhooks

Create an endpoint with client.webhook_endpoints.create({"url": ..., "event_types": [...]}). The secret is shown once. Events today: call.started, call.completed, agent.published. Check every delivery before you trust it, using the raw body bytes:

from voiflow import verify_webhook_signature, parse_webhook_event

verify_webhook_signature(raw_body, request.headers["VoiFlow-Signature"], secret)  # raises if wrong or older than 5 minutes
event = parse_webhook_event(raw_body)  # event["id"] stays the same on retries: use it to skip duplicates

Before you place calls

Phone calls and browser voice sessions work once VoiFlow has connected a phone line to the business, which VoiFlow does for you during onboarding. Until then calls.create and sessions.create raise a clear error saying so. Webhook endpoints must be public https addresses.

What is in the client

Upload a document: client.files.upload(pdf_bytes, filename="policy.pdf", content_type="application/pdf").

Field names are the same as in the API reference (agent_id, contact_id).

MIT licence.