Metadata-Version: 2.4
Name: voiflow
Version: 0.1.1
Summary: VoiFlow 4.0 server-side SDK for the public /v1 API: businesses, agents, journeys, calls, conversations, campaigns, AI work, webhooks.
License-Expression: MIT
Project-URL: Homepage, https://voiflow.ai
Keywords: voiflow,voice,ai,phone,calls,sdk,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# VoiFlow for Python

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

```bash
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

```python
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.

```python
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:

```python
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

| Group | Methods |
|---|---|
| `businesses` | list, create, retrieve, update, readiness, settings, update_settings |
| `agents` | list, create, retrieve, update, delete, publish, voice_options |
| `journeys` | list, create, retrieve, update, draft, save_draft, create_version, retrieve_version, publish, impact |
| `calls` | list, create, retrieve, end, steer, transcript, recording, stream |
| `conversations` | list, create, retrieve, list_messages, send_message, takeover, resume_ai |
| `contacts` | list, create, retrieve, update, set_dnc |
| `enquiries` | list, retrieve |
| `appointments`, `calendar` | appointments.list / create; calendar.availability / resources |
| `knowledge`, `files` | knowledge.list / create / update / publish; files.list / upload / retrieve / download |
| `projects`, `campaigns`, `runs` | projects.list / create; campaigns.list / create / retrieve / update / set_status / stats; runs.create / retrieve / stats |
| `connections`, `integrations`, `channel_accounts`, `lines` | connections.list / create / retrieve / update / readiness; integrations.list; channel_accounts.list / create; lines.list / update |
| `ai_work` | list, retrieve, cancel, requeue |
| `webhook_endpoints`, `events` | webhook_endpoints.list / create / retrieve / update / delete / rotate_secret / list_deliveries; events.list / replay |
| `sessions`, `usage`, `limits`, `operations` | sessions.create; usage.get / costs; limits.get; operations.retrieve |

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.
