virturing 0.2.0

Server-side Python SDK for the Virturing Voice API

Virturing Python SDK

Dependency-free synchronous and asynchronous clients for Python 3.10+.

import os
from virturing import Virturing

voice = Virturing(os.environ["VIRTURING_API_KEY"])
call = voice.create_call(
    agent_id="agent_uuid",
    phone_number_id="number_uuid",
    to_number="[phone]",
    channel="ai",
    metadata={"employee_id": "EMP-1042", "shift": "morning"},
)

To keep an existing Twilio number and carrier account, point its incoming-call webhook to the connector URL shown in Virturing. Start outgoing calls through that connector with:

call = voice.create_twilio_call(
    connector_id="connector_uuid",
    agent_id="agent_uuid",
    to_number="[phone]",
    metadata={"customer_ref": "CUST-1042"},
    idempotency_key="customer-call-CUST-1042",
)

Twilio continues to bill the carrier leg; Virturing deducts only metered AI/platform usage from the USD wallet.

To use a Virturing number with your own AI or media server, register a WSS endpoint and start a programmable call:

created = voice.create_media_endpoint(
    name="My voice service",
    url="wss://voice.example.com/virturing/media",
)
# Store created["signing_secret"] once in your server-side secret manager.
voice.create_programmable_call(
    phone_number_id="number_uuid",
    media_endpoint_id=created["endpoint"]["id"],
    to_number="[phone]",
)

verify_media_stream_signature authenticates the WSS opening handshake. The stream uses bidirectional PCM16 mono audio at 8 kHz. See docs/programmable-media.md for the complete contract and customer-hosted Python and Node examples.

The client automatically uses idempotency keys and retries only safe operations. Keep the API key in server-side secrets. verify_webhook_signature validates the exact raw request body before JSON parsing.

Use Virturing(client_id=..., client_secret=..., scopes=[...]) for OAuth client credentials. Access tokens are cached and refreshed automatically. create_media_session(...) creates a metered realtime voice session for a web, desktop, or mobile client.