Viantrix Documentation

Viantrix is a real-time voice platform that enables enterprises to build secure, multilingual voice experiences that integrate seamlessly with telephony systems and CRMs. Our platform provides the tools to create, manage, and scale voice interactions across multiple channels with enterprise-grade reliability.

Key features include:

• Secure, encrypted voice communications
• Multilingual support with automatic language detection
• Pre-built integrations with major telephony providers
• CRM integrations for contextual conversations
• Advanced analytics and quality assurance tools
• Compliance with regional regulations (GDPR, DLT, etc.)

Get started with Viantrix in just three simple steps:

curl -X POST https://api.viantrix.com/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_123",
    "to": "+15551234567",
    "locale": "en-US",
    "webhookUrl": "https://your-webhook.url"
  }'

const response = await fetch('https://api.viantrix.com/v1/calls', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agentId: 'agent_123',
    to: '+15551234567',
    locale: 'en-US',
    webhookUrl: 'https://your-webhook.url'
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.viantrix.com/v1/calls',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'agentId': 'agent_123',
        'to': '+15551234567',
        'locale': 'en-US',
        'webhookUrl': 'https://your-webhook.url'
    }
)

data = response.json()

// Note: Browser requests may require CORS configuration
const response = await fetch('https://api.viantrix.com/v1/calls', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agentId: 'agent_123',
    to: '+15551234567',
    locale: 'en-US',
    webhookUrl: 'https://your-webhook.url'
  })
});

const data = await response.json();

Before diving deeper, familiarize yourself with these core concepts:

• Agents: The virtual personas that handle voice interactions
• Flows: Conversation workflows that define the interaction logic
• Webhooks: Event notifications sent to your servers
• Telephony: The underlying voice infrastructure
• Security: Encryption, authentication, and compliance features

Agents are the virtual personas that handle voice interactions with your users. Each Agent has:

• A persona (name, voice characteristics, tone)
• SSML rules for speech synthesis
• Interruption handling configuration
• Locale fallback for multilingual support
• Prompt templates for common responses

Flows define the conversation logic that your Agents follow. A Flow consists of nodes connected by branching conditions:

• Gather: Collect user input (voice or DTMF)
• Validate: Verify input meets criteria
• Transfer: Hand off to another Flow or human agent
• End: Terminate the conversation

Each node can have multiple branches based on conditions like:

• User input matching specific patterns
• Timeouts or no input
• External API responses
• Retry counts

Viantrix provides high-quality voice capabilities with:

• STT/TTS engines: Multiple engine options optimized for different languages
• Latency targets: <500ms for most interactions
• Barge-in: Allow users to interrupt the Agent
• Silence detection: Automatic handling of dead air
• Emotion modulation: Adjust tone based on context

Viantrix integrates with multiple telephony providers for PSTN and SIP connectivity:

• SIP/PSTN: Connect to existing telephony infrastructure
• India routes: Specialized connectivity for Indian numbers
• DTMF: Support for touch-tone input
• Recordings governance: Configurable recording policies
• Caller ID: Customizable display numbers

Webhooks allow Viantrix to send real-time event notifications to your servers:

• Signed events: Verifiable message authenticity
• Retries: Automatic retry for failed deliveries
• Idempotency keys: Prevent duplicate processing
• Event catalog: Comprehensive event types

Common webhook events include:

• call.started
• speech.detected
• transfer.initiated
• voicemail.detected
• call.completed

Viantrix provides enterprise-grade security features:

• PII scopes: Fine-grained access to sensitive data
• Encryption: At rest and in transit
• Retention: Configurable data retention policies
• Audit exports: Comprehensive activity logs
• Regional hosting: Data residency options

Authenticate with the Viantrix API using Bearer tokens in the Authorization header:

Authorization: Bearer sk_live_1234567890abcdef1234567890abcdef

API keys have specific scopes that determine which endpoints they can access. Create keys with the minimum required permissions.

The Calls API allows you to initiate and manage voice interactions.

POST /v1/calls

Create a new call.

{
  "agentId": "agent_123",
  "to": "+15551234567",
  "locale": "en-US",
  "webhookUrl": "https://your-webhook.url",
  "metadata": {
    "customerId": "cust_789",
    "orderNumber": "ORD-2023-456"
  }
}

GET /v1/calls/{id}

Retrieve call status and details.

POST /v1/calls/{id}/transfer

Initiate a warm transfer to another number or agent.

POST /v1/calls/{id}/voicemail-detect

Check if the call was answered by voicemail.

Manage your virtual Agents through the API:

• Create: Define a new Agent with persona and capabilities
• Retrieve: Get Agent details and configuration
• Update: Modify Agent settings
• Delete: Remove an Agent
• List: Browse all available Agents

Agents support multiple languages, prompt templates, and SSML customization.

The Flows API allows you to:

• Import/export flow JSON definitions
• Publish versions for production use
• Test flows in sandbox mode
• Analyze flow performance

Each Flow version is immutable once published, ensuring consistent behavior.

Configure webhook endpoints and manage event subscriptions:

• Create: Set up a new webhook endpoint
• Verify: Confirm endpoint ownership
• List: View all configured webhooks
• Update: Modify webhook settings
• Delete: Remove a webhook

Webhooks support retry logic and can be tested from the dashboard.

Viantrix emits a comprehensive set of events that can trigger webhooks or be queried via API:

The Viantrix JavaScript SDK works in both browser and Node.js environments:

npm install @viantrix/sdk

import { Viantrix } from '@viantrix/sdk';

const client = new Viantrix({
  apiKey: 'YOUR_API_KEY'
});

// Initiate a call
const call = await client.calls.create({
  agentId: 'agent_123',
  to: '+15551234567',
  locale: 'en-US'
});

console.log('Call ID:', call.id);

The Viantrix Python SDK provides a convenient interface for server-side integration:

pip install viantrix

from viantrix import Client

client = Client(api_key="YOUR_API_KEY")

# Create a call
call = client.calls.create(
    agent_id="agent_123",
    to="+15551234567",
    locale="en-US"
)

print(f"Call ID: {call.id}")

Common Node.js backend integration patterns:

Express Webhook Handler

const express = require('express');
const { ViantrixWebhook } = require('@viantrix/sdk');

const app = express();
app.use(express.json());

const webhookSecret = 'YOUR_WEBHOOK_SECRET';

app.post('/webhook', ViantrixWebhook(webhookSecret), (req, res) => {
  const event = req.body;
  
  switch (event.type) {
    case 'call.started':
      console.log(`Call ${event.data.id} started`);
      break;
    case 'call.completed':
      console.log(`Call ${event.data.id} completed after ${event.data.duration}s`);
      break;
    // Handle other event types
  }
  
  res.status(200).end();
});

app.listen(3000);

Agent Configuration Manager

const { Viantrix } = require('@viantrix/sdk');
const client = new Viantrix({ apiKey: 'YOUR_API_KEY' });

async function updateAgentLanguages(agentId, languages) {
  const agent = await client.agents.retrieve(agentId);
  
  return client.agents.update(agentId, {
    ...agent,
    languages: [...new Set([...agent.languages, ...languages])]
  });
}

// Usage
updateAgentLanguages('agent_123', ['en-US', 'es-MX'])
  .then(updatedAgent => {
    console.log('Updated agent languages:', updatedAgent.languages);
  });

India's telecom regulations require businesses to register their caller IDs to prevent spam. This guide walks through setting up Branded Caller ID for your Indian numbers.

How it works

When calling Indian numbers, your business name (instead of a random number) will be displayed to recipients who have your number saved in their contacts.

Registration steps

1. Submit your business registration documents
2. Provide a list of phone numbers to be branded
3. Wait for approval (typically 5-7 business days)
4. Configure your Viantrix account with the approved IDs

Sample Payload

{
  "to": "+919876543210",
  "agentId": "agent_123",
  "locale": "en-IN",
  "callerId": {
    "brandId": "BRAND123",
    "templateId": "TEMPLATE456"
  }
}

Warm transfer allows your virtual Agent to introduce the caller to a human agent before completing the transfer, creating a seamless experience.

Implementation

1. Configure an operator endpoint (phone number or SIP URI)
2. Define hold music or whisper prompts
3. Add a Transfer node to your Flow
4. Handle transfer success/failure cases

POST /calls/{id}/transfer Example

{
  "to": "+15559876543",
  "whisper": "You're receiving a transfer from our virtual assistant. The caller needs help with their recent order.",
  "holdMusic": "https://example.com/hold-music.mp3"
}

Common Errors

Connect Viantrix to Google Calendar or Microsoft Outlook to enable intelligent call scheduling based on availability.

Setup

1. Configure OAuth with your calendar provider
2. Set up webhook for booking confirmations
3. Create a Flow that checks availability
4. Define booking confirmation logic

Busy/Free Check

{
  "available": false,
  "nextAvailable": "2025-09-10T14:30:00Z",
  "calendarId": "user@example.com",
  "duration": 30
}

Initiate multiple calls simultaneously with rate limiting and concurrency controls.

CSV Format

Upload a UTF-8 CSV with the following headers:

to,agentId,locale,webhookUrl,metadata.customerId
+15551230001,agent_123,en-US,https://your-webhook.url,cust_1001
+15551230002,agent_123,en-US,https://your-webhook.url,cust_1002
+15551230003,agent_123,hi-IN,https://your-webhook.url,cust_1003

Rate Limits & Concurrency

• Requests: 10 req/sec per API key (burstable to 50 for 30s).
• Concurrent calls: Default cap 500; contact support to raise.
• Backoff: Use exponential backoff on HTTP 429 with jitter.
• Pause/Resume: PATCH your batch to state=paused|running.

Progress Webhooks

Subscribe to progress events to track batch state:

Bridge voice and WhatsApp for follow-ups, confirmations, and deferred flows.

Template Approval & Opt-in

• Register sender, business verification, and get templateId approved.
• Capture explicit user opt-in and store timestamp + source.

Voice → WhatsApp Handoff

{
  "callId": "call_abc123",
  "channel": "whatsapp",
  "to": "+919876543210",
  "templateId": "order_followup_v1",
  "params": {
    "name": "Aarav",
    "orderNumber": "ORD-2025-001"
  }
}