Virturing API & SDK Reference

Integrate real-time carrier voice networks, customize AI speech-to-text workflows, and hook external telephony lines (like Twilio) into Asia's first programmable voice operating system.

Quickstart & Authentication

Virturing authorizes requests using scoped API Keys or OAuth Client Credentials. Credentials grant secure, rate-limited access to local carrier channels and active routing engines.

Environment Settings

// Set up your environment variable
VIRTURING_API_KEY="vt_live_..."

// Set up your client credentials if using OAuth
VIRTURING_CLIENT_ID="cli_..."
VIRTURING_CLIENT_SECRET="sec_..."

On-Chain USD Ledger holds

To protect networks from bad actors and balance exhaustion, Virturing implements transaction-level holds:

Pre-Call Reserve: An initial hold is reserved from your balance when starting a call.
Dynamic heartbeats: Holds are settled/extended dynamically every 20 seconds during active connections.
Zero-Debt Ceiling: Calls automatically tear down with high priority if your wallet falls below the active threshold.

TypeScript SDK Reference

Install the official `@virturing/sdk` library to initiate calls, program custom agent routing tables, and verify webhooks safely inside Node 18+ environments.

Install command:npm i @virturing/sdk

TypeScript Quickstart

import { Virturing } from "@virturing/sdk";

// Initialize client (reads VIRTURING_API_KEY automatically)
const client = new Virturing({
  apiKey: process.env.VIRTURING_API_KEY
});

// 1. Create a Standard AI Call
const call = await client.createCall({
  agentId: "agent_abc123",
  recipientPhone: "+60123456789", // Malaysia format
  callerId: "+60399998888",
});
console.log(`Call initiated. ID: ${call.id}`);

// 2. Create a Twilio Outbound Connector Call
const twilioCall = await client.createTwilioCall({
  agentId: "agent_abc123",
  recipientPhone: "+6598765432", // Singapore format
  connectorId: "conn_tw_xyz789", // Connects directly to your own Twilio numbers
});

// 3. Verify incoming webhook signatures safely
const isValid = client.verifyWebhookSignature({
  payload: rawRequestBody,
  signature: req.headers["x-virturing-signature"],
  signingSecret: "whsec_..."
});

Python SDK Reference

Our Python SDK is 100% dependency-free, built entirely using Python's standard urllib libraries to eliminate container bloat and deployment issues.

Install command:pip install virturing

Python Quickstart

from virturing import Virturing
import os

# Initialize the dependency-free standard client
client = Virturing(
    api_key=os.environ.get("VIRTURING_API_KEY")
)

# 1. Initiate an outbound AI agent call
call = client.create_call(
    agent_id="agent_abc123",
    recipient_phone="+60123456789",
    caller_id="+60399998888"
)
print(f"Call started with ID: {call['id']}")

# 2. Schedule a call for a future calendar event
scheduled = client.schedule_call(
    agent_id="agent_abc123",
    recipient_phone="+60123456789",
    scheduled_time="2026-08-01T10:00:00Z"
)

# 3. Verify incoming webhook signature
is_valid = client.verify_webhook_signature(
    payload=raw_request_bytes,
    signature=headers.get("X-Virturing-Signature"),
    signing_secret="whsec_..."
)

Java SDK Reference

Integrate Virturing inside Java 17+ JVM applications using type-safe builders, Jackson deserialization, and automatic socket connection retries.

Gradle dependency:implementation 'ai.virturing:virturing-java:1.0.0'

Java Quickstart

import ai.virturing.VirturingClient;
import ai.virturing.models.*;

public class Main {
    public static void main(String[] args) throws Exception {
        // Initialize client with Builder pattern
        VirturingClient client = VirturingClient.builder()
            .apiKey(System.getenv("VIRTURING_API_KEY"))
            .build();

        // 1. Create call request parameters
        CreateCallRequest request = CreateCallRequest.builder()
            .agentId("agent_abc123")
            .recipientPhone("+60123456789")
            .callerId("+60399998888")
            .build();

        // 2. Execute outbound call
        CallResponse response = client.createCall(request);
        System.out.println("Call status: " + response.getId());
    }
}

WebSocket Media Bridge

Direct raw voice channels to custom LLMs or recording nodes under 300ms round-trip delay using Virturing's full-duplex binary audio sockets.

Handshake & Payload Contract

# WSS Handshake request headers:
GET /v1/media-bridge/connect HTTP/1.1
Host: your-media-server.com
X-Virturing-Call-Id: call_123abc
X-Virturing-Timestamp: 1784458096
X-Virturing-Media-Signature: a3b2f8c9... # HMAC-SHA256 of headers

# Full-Duplex PCM Binary audio payload contract:
# - Format: 16-bit Signed Little-Endian Linear PCM
# - Sample Rate: 8 kHz mono (8000 samples per second)
# - Audio Packets: 20 ms frames (320 bytes of raw payload)
# - Direction: Bidirectional binary WebSocket frames

Audio Contract Specs

PCM Format: Signed 16-bit little-endian linear PCM.
Rate/Channels: 8 kHz mono (standard G.711 carrier quality).
Packets: 20 ms frames (320 bytes per frame payload).

Webhook Security

Virturing signs all webhook event request payloads with HMAC signatures to prevent injection and replay attacks on your server endpoints.

Safe Checks: Always use constant-time byte checks to compare webhook signatures and prevent timing leak vulnerability vectors.

Campaign Dialer API

Run automated call outreach campaigns with strict concurrent channel limiters. The system handles active dialing, carrier rate tables, and user queue handoffs dynamically.

POST /v1/campaigns/dial

POST /v1/campaigns/dial
Authorization: Bearer vt_live_...
Content-Type: application/json

{
  "campaignId": "camp_987xyz",
  "concurrencyLimit": 15,
  "agentId": "agent_abc123",
  "recipients": [
    { "phone": "+60123456789", "name": "Namith" },
    { "phone": "+6598765432", "name": "Lia" }
  ]
}

Ready to deploy?

Build voice OS integrations on the Sandbox.

Access Dashboard