Virturing TypeScript SDK

Server-side SDK for Node.js 18+.

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

const voice = new Virturing({ apiKey: process.env.VIRTURING_API_KEY! });
const call = await voice.createCall({
  agent_id: "agent_uuid",
  phone_number_id: "number_uuid",
  to_number: "+94771234567",
  channel: "ai",
  metadata: { employee_id: "EMP-1042", shift: "morning" },
});

Use a dynamic agent when trusted server code creates a one-off task:

const call = await voice.createDynamicCall({
  phone_number_id: "number_uuid", // Or connector_id for your own carrier.
  to_number: "+94771234567",
  dynamic_agent: {
    name: "Attendance confirmation",
    instructions: "Confirm attendance. Never infer an answer the caller did not give.",
    first_message: "Hello, I am calling to confirm your attendance tomorrow.",
    voice_performance_profile: "balanced",
    output_fields: [{
      extractionType: "ai",
      name: "attending",
      description: "Whether the recipient confirms attendance.",
      resultFormat: "boolean",
      exampleOutput: "true",
      required: true,
      confirmation: "explicit",
    }],
  },
  metadata: { employee_id: "EMP-1042" },
}, { idempotencyKey: "attendance-EMP-1042" });

The inline configuration is validated, frozen, and retained with the call for retries and audit. It is not added to the workspace agent list. The same payload can be used in createCallBatch or scheduleCall.

For a monitoring alert, create a one-way alert agent in the portal and send the exact text from trusted server code. Virturing calls through the selected owned number, speaks the message with the alert agent's configured voice, and hangs up:

const alert = await voice.createAlertCall({
  agent_id: "alert_agent_uuid",
  phone_number_id: "number_uuid",
  to_number: "+94771234567",
  message: "Production alert. Checkout latency has exceeded two seconds.",
  metadata: { incident_id: "INC-2042" },
}, { idempotencyKey: "incident-INC-2042" });

Alert calls do not start STT, an LLM, tools, or a conversational workflow. Carrier usage and generated TTS audio are still prepaid and metered.

To keep an existing Twilio number and carrier account, point the number's incoming-call webhook to the connector URL shown in Virturing. Outgoing calls use the same connector directly:

const call = await voice.createTwilioCall({
  connector_id: "connector_uuid",
  agent_id: "agent_uuid",
  to_number: "+94771234567",
  metadata: { customer_ref: "CUST-1042" },
}, { idempotencyKey: "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:

const { endpoint, signing_secret } = await voice.createMediaEndpoint({
  name: "My voice service",
  url: "wss://voice.example.com/virturing/media",
});
// Store signing_secret once in your server-side secret manager.
await voice.createProgrammableCall({
  phone_number_id: "number_uuid",
  media_endpoint_id: endpoint.id,
  to_number: "+94771234567",
});

verifyMediaStreamSignature 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.

For OAuth client credentials, initialize with clientId, clientSecret, and optional scopes instead. Tokens are cached and refreshed automatically. createMediaSession returns a short-lived LiveKit participant token for metered web or app voice sessions.

Create calls only from trusted server code. The SDK generates idempotency keys, retries safe requests on temporary failures, applies timeouts, and returns typed API errors. Pass your own idempotencyKey when a business operation already has a stable ID.