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.

Get your API key

The SDK signs in with an API key, not a username and password.

1. Sign in to the Partner Portal at https://partners.voiflow.ai with your partner account.
2. Open Developers, then API keys, then New key. Choose test or live, which businesses it covers and what it may do.
3. Copy the key when it is shown. It is displayed once; if you lose it, rotate it in the same screen.
4. Keep it on your server, for example in an environment variable called VOIFLOW_API_KEY, and pass it in as shown below. Never put it in browser code or a public repository.

Don't have a partner account yet? Request API access at https://voiflow.ai and VoiFlow will set you up.

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"])

Choose the page size with limit (at most 100); the iterator still walks every page:

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

Types

Responses and request bodies are typed dictionaries, so your editor and type checker know every field:

from voiflow.models import Agent, CallCreate

agent: Agent = client.agents.retrieve("agent_id")
body: CallCreate = {"agent_id": agent["id"], "contact_id": "contact_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.