# Vobiz API Documentation

> Generated for LLM Context



---

# Page: /

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'key-features', title: 'Key Features', level: 2 },
{ id: 'getting-started', title: 'Getting Started', level: 2 },
{ id: 'authentication-overview', title: 'Authentication Overview', level: 2 },
{ id: 'account-scoped', title: 'Account-Scoped Resources', level: 2 }
];
const handleDownloadCollection = () => {
const link = document.createElement('a');
link.href = '/Postman_Vobiz.json';
link.download = 'Vobiz_API_Collection.postman_collection.json';
document.body.appendChild(link);
link.click();
document.body.removeChild(link);
};
return (
{/* Header Section */}
# Vobiz API Documentation
Complete API documentation for building enterprise-grade telephony solutions. Provision SIP trunks, manage phone numbers, route calls, and track usage with our powerful REST APIs.
Download Postman Collection
LLM Context
https://api.vobiz.ai
{/* Feature Overview */}
### Core Features
#### SIP Trunk Provisioning
Auto-generated domains (`trunkId.sip.vobiz.ai`) with configurable codecs, rate limits, and authentication
#### Call Routing & LCR
Intelligent least-cost routing with prefix-based rules and carrier priority management
#### Number Management
Search, purchase, and assign phone numbers with auto-billing
#### Real-time Billing
Multi-currency balance management, CDR processing, and Razorpay payment integration
### API Features
#### RESTful API
Standard HTTP methods (GET, POST, PUT, DELETE) with JSON request and response format
#### Header-Based Authentication
Secure header-based authentication using X-Auth-ID and X-Auth-Token for all API endpoints.
#### Multi-Tenancy
Account-scoped resources with sub-account support for SaaS and reseller models
#### Rate Limiting
CPS (calls per second) and concurrent call limits
{/* Getting Started */}
## Getting Started
### Base URL
```
X-Auth-ID: {your_auth_id}
X-Auth-Token: {your_auth_token}
```
{/* Account-Scoped Resources */}
## Account-Scoped Resources
**All resource APIs** follow a strict account-scoped pattern for security and multi-tenancy:
```
https://api.vobiz.ai/api/v1/account/{accountID}/resource
Examples:
GET  https://api.vobiz.ai/api/v1/account/MA_2210JXXN/trunks
POST https://api.vobiz.ai/api/v1/account/MA_2210JXXN/trunks
GET  https://api.vobiz.ai/api/v1/account/MA_2210JXXN/balance
POST https://api.vobiz.ai/api/v1/account/MA_2210JXXN/numbers/purchase
```
**Important:** The Gateway validates that the account_id associated with your authentication credentials matches the accountID in the URL path. This ensures complete data isolation between accounts.
**Exception:** Sub-account endpoints use `/accounts/` (plural) with trailing slash:
https://api.vobiz.ai/api/v1/accounts/{'{accountId}'}/sub-accounts/
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /quick-start

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'sign-up', title: 'Step 1: Sign Up', level: 2 },
{ id: 'dashboard', title: 'Step 2: Dashboard Overview', level: 2 },
{ id: 'buy-number', title: 'Step 3: Buy a Phone Number', level: 2 },
{ id: 'sip-trunks', title: 'Step 4: Create SIP Trunks', level: 2 },
{ id: 'xml-application', title: 'Step 5: Create an XML Application', level: 2 },
{ id: 'transactions', title: 'Step 6: View Transactions', level: 2 },
{ id: 'cdrs', title: 'Step 7: View Call Records (CDRs)', level: 2 },
];
return (
# Quick Start Guide
Welcome to Vobiz! This guide will walk you through the essential steps to get started with our platform.
## Introduction
This guide will walk you through the basic steps to get your Vobiz account set up and ready to make and receive calls. We'll cover everything from signing up to creating your first application.
## Step 1: Sign Up
First, you'll need to create a Vobiz account. You can register for a new account at our [registration page](https://console.vobiz.ai/app/register).
## Step 2: Dashboard Overview
Once you've signed up, you'll be taken to your dashboard. We provide you with ₹645 in credit to get started. You can use this to buy a phone number and start using our services.
## Step 3: Buy a Phone Number
You can purchase a phone number from the "DID" section of the console. You can filter numbers by region to find the perfect one for your needs.
## Step 4: Create SIP Trunks
SIP trunks are essential for connecting your existing infrastructure to the Vobiz platform. Here’s how to set up both outbound and inbound trunks:
### Outbound Trunks
First, create an outbound trunk. This will allow you to make calls from your Vobiz account.
Next, you'll need to create credentials for your outbound trunk. This will ensure that your calls are secure.
### Inbound Trunks
To receive calls, you'll need to link your phone number to an inbound trunk.
You can also set up an inbound URI to route calls to your own infrastructure.
## Step 4.1: Integrations
Vobiz can be integrated with a variety of other platforms to extend its functionality. You can find detailed guides for each integration on our [integrations page](/integrations). Some of our most popular integrations are:
- [Vapi](/integrations/vapi)
- [ElevenLabs](/integrations/elevenlabs)
- [Retell AI](/integrations/retellai)
## Step 5: Create an XML Application
In the "Voice" section, you can create an XML application to control your call flow. You can configure various URLs to handle different call events.
After you've configured your application, you can assign your purchased phone number to it. This will link your number to the application's logic, enabling inbound calls.
## Step 6: View Transactions
You can view all of your transactions in the "Transactions" section. This will show you a history of all the charges and credits to your account.
## Step 7: View Call Records (CDRs)
You can view all of your call detail records (CDRs) in the "CDR" section. This will show you a history of all the calls you've made and received.
);
}

---

# Page: /postman-guide

'use client';
const handleDownloadCollection = () => {
const link = document.createElement('a');
link.href = '/Postman_Vobiz.json';
link.download = 'Vobiz_API_Collection.postman_collection.json';
document.body.appendChild(link);
link.click();
document.body.removeChild(link);
};
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'download', title: 'Download Collection', level: 2 },
{ id: 'import', title: 'Import into Postman', level: 2 },
{ id: 'environment', title: 'Environment Setup', level: 2 },
{ id: 'authentication', title: 'Configure Authentication', level: 2 },
{ id: 'workflow', title: 'Testing Workflow', level: 2 },
{ id: 'variables', title: 'Collection Variables', level: 2 },
{ id: 'tips', title: 'Tips & Tricks', level: 2 }
];
return (
{/* Header Section */}
# Postman Collection Guide
Get started quickly with our comprehensive Postman collection. Includes all API endpoints with pre-configured requests, automatic variable management, and example workflows.
### What's Included
- 130+ pre-configured API requests across all services
- Automatic token refresh and variable management
- Pre/post-request scripts for seamless testing
- Example data and realistic payloads
{/* Download Collection */}  ## Download Collection   Download the complete Postman collection with all API endpoints, authentication, and example requests.
Download Postman Collection   #### Collection File `Vobiz_API_Collection.postman_collection.json` Latest version - Updated with all endpoints from Gateway, Account, Trunk, Number, Balance, and CDR services
{/* Import into Postman */}
## Import into Postman
#### Step 1: Open Postman
Launch Postman desktop app or visit [postman.com](https://www.postman.com) for the web version.
#### Step 2: Import Collection
- Click **Import** button in the top-left corner
- Drag and drop the JSON file or click **Upload Files**
- Select `Vobiz_API_Collection.postman_collection.json`
- Click **Import** to confirm
#### Step 3: Verify Import
You should see a new collection named "VoBiz SIP Trunking Platform" in your Collections sidebar with the following folders:
- Gateway
- Account Service → Authentication
- Account Service → Accounts
- Account Service → Sub-Accounts
- Trunk Service
- Number Service
- Balance Service
- CDR Processor
{/* Environment Setup */}
## Environment Setup
Create a Postman environment to manage API base URLs and credentials across different deployment stages.
#### Create New Environment
- Click the **Environments** tab in the left sidebar
- Click **Create Environment** or the **+** button
- Name it "Vobiz - Production" (or Development/Staging)
#### Configure Variables
Variable
Initial Value
Description
`base_url`
`https://api.vobiz.ai`
API base URL
`email`
`your@email.com`
Your account email
`password`
`yourpassword`
Your account password
`access_token`
(leave empty)
Auto-populated after login
`refresh_token`
(leave empty)
Auto-populated after login
`accountId`
(leave empty)
Auto-populated after login
#### Activate Environment
Select your environment from the dropdown in the top-right corner of Postman. The collection will automatically use these variables in all requests.
{/* Configure Authentication */}
## Configure Authentication
The collection includes automatic authentication handling via pre-request scripts.
#### Automatic Login Flow
- Open the **Authentication** folder
- Run the **Login** request
- The script will automatically save `access_token`, `refresh_token`, and `accountId` to your environment
- All subsequent requests will use these tokens in the `Authorization` header
#### Token Refresh
If your access token expires (default: 30 minutes), simply run the **Refresh Access Token** request. The new token will be automatically saved to your environment.
### Security Note  Never commit environment files with real credentials to version control. Use separate environments for development, staging, and production.
{/* Testing Workflow */}
## Testing Workflow
Follow this recommended workflow to test the complete API stack:
#### 1. Authentication
- Login with your provided credentials → saves tokens automatically
- Get Current User Info → verify authentication
#### 2. SIP Trunk Provisioning
- Create SIP Trunk → note the `trunkId`
- List SIP Trunks → verify creation
- Get SIP Trunk Details → check domain assignment
#### 3. Balance Management
- Get Balance → check initial balance
- Credit Balance → add funds
- List Transactions → verify credit
#### 4. Phone Numbers
- Search Numbers → find available numbers
- Purchase Number → buy a number
- Assign to Trunk → link number to trunk
- List Numbers → verify ownership
#### 5. Call Testing
- Configure your SIP client with trunk credentials
- Make test calls
- List CDRs → verify call records
- Check Balance → confirm call deductions
{/* Collection Variables */}
## Collection Variables
The collection uses variables to chain requests together seamlessly. These are automatically set by post-request scripts:
Variable
Set By
Used In
`access_token`
Login request
All authenticated endpoints
`accountId`
Login request
Account-scoped API paths
`trunkId`
Create Trunk
Get/Update/Delete trunk requests
`numberId`
Purchase Number
Assign/Release number requests
`subAccountId`
Create Sub-Account
Sub-account operations
`routingRuleId`
Create Routing Rule
Update/Delete routing rule
{/* Tips & Tricks */}
## Tips & Tricks
### Use Collection Runner
Select the collection → Click **Run** → Execute all requests sequentially to test the entire workflow. Great for regression testing after API changes.
### Console Debugging
Open Postman Console (View → Show Postman Console) to see detailed request/response logs, including pre-request script output and variable changes.
### Save Responses as Examples
After successful requests, click **Save Response** → **Save as Example**. This helps document expected response formats for your team.
### Export for CI/CD
Use Newman (Postman's CLI) to run collections in your CI/CD pipeline: ` npm install -g newman newman run collection.json -e environment.json `
### Mock Servers
Create a Postman Mock Server from the collection for frontend development before backend APIs are ready. Right-click collection → **Mock Collection**.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/overview

const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'authentication', title: 'Authentication', level: 2 },
{ id: 'call-operations', title: 'Call Operations', level: 2 }
];
const callOperations = [
{
name: 'Make a Call',
href: '/call/make-call',
description: 'Initiate an outbound call to a PSTN number or SIP endpoint.'
},
{
name: 'Machine Detection',
href: '/call/machine-detection',
description: 'Detect answering machines on outbound calls with synchronous or asynchronous detection modes.'
},
{
name: 'Transfer a Call',
href: '/call/transfer-call',
description: 'Transfer an ongoing call to fetch and execute XML from a different URL. Transfer A-leg, B-leg, or both.'
},
{
name: 'Hang Up a Call',
href: '/call/hangup-call',
description: 'Hang up an ongoing call or cancel a queued outbound call.'
},
{
name: 'Retrieve a Live Call',
href: '/call/retrieve-live-call',
description: 'Get details of a specific ongoing call in real-time using its call UUID.'
},
{
name: 'Retrieve All Live Calls',
href: '/call/retrieve-all-live-calls',
description: 'Get a list of all ongoing calls (v1). Returns an array of call UUIDs for currently active calls.'
},
{
name: 'Retrieve a Queued Call',
href: '/call/retrieve-queued-call',
description: 'Get details of a specific queued outbound call that has not yet been initiated using its call UUID.'
},
{
name: 'Retrieve All Queued Calls',
href: '/call/retrieve-all-queued-calls',
description: 'Get a list of all queued outbound calls. Returns up to 20 queued calls per request.'
},
{
name: 'Record Calls',
href: '/call/record-calls',
description: 'Record call audio in MP3 or WAV format with automatic transcription support. Start and stop recording during active calls.'
},
{
name: 'Play Audio on Calls',
href: '/call/play-audio',
description: 'Play audio files during active calls. Support for single or multiple audio files, looping, and selective playback to caller or callee.'
},
{
name: 'Speak Text on Calls',
href: '/call/speak-text',
description: 'Convert text to speech and play during active calls. Support for 29 languages with multiple voice options.'
},
{
name: 'DTMF',
href: '/call/dtmf',
description: 'Send DTMF digits during active calls for IVR navigation and menu selection.'
}
];
return (
{/* Header */}
# Call Management Overview
Comprehensive control over voice calls, including making calls, call control operations, recording, playing audio, text-to-speech, and DTMF digit sending.
{/* Introduction Section */}
## Introduction
A Call object is created when an outbound call is initiated or when an inbound call is received. You can use a Call object to interact with ongoing calls, retrieve details about completed calls, and transfer ongoing calls, thereby building custom call flows.
### Base URL
https://api.vobiz.ai/api
### Endpoint
https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Call/
{/* Authentication Section */}
## Authentication
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
#### Example Request Headers
X-Auth-ID: {'{Auth_ID}'}
X-Auth-Token: YOUR_AUTH_TOKEN
Content-Type: application/json
{/* Call Operations */}
## Call Operations
{callOperations.map((operation) => (
{operation.name}
{operation.description}
View Documentation →
))}
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/call-object

const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 }
];
return (
{/* Header */}
# The Call Object
The Call object contains all information about a voice call, including metadata, status, duration, and billing details.
{/* Introduction */}
A Call object is created when an outbound call is initiated or when an inbound call is received. You can use the Call object to interact with ongoing calls, retrieve details about completed calls, and transfer ongoing calls, thereby building custom call flows.
**Note:** Call objects are automatically created for both inbound and outbound calls. Each call has a unique `call_uuid` that can be used to retrieve call details or perform operations on the call.
{/* Attributes */}
## Attributes
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/make-call

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'required-parameters', title: 'Required Parameters', level: 2 },
{ id: 'callback-parameters', title: 'Callback Parameters', level: 2 },
{ id: 'machine-detection-parameters', title: 'Machine Detection Parameters', level: 2 },
{ id: 'advanced-parameters', title: 'Advanced Parameters', level: 2 },
{ id: 'request-example', title: 'Request Example', level: 2 },
{ id: 'response-example', title: 'Response Example', level: 2 },
{ id: 'callback-parameters-sent', title: 'Callback Parameters Sent', level: 2 }
];
return (
{/* Header */}
# Make an Outbound Call
Initiate an outbound call to a PSTN number or a SIP endpoint, and make simultaneous bulk calls.
{/* Introduction */}
POST
`https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Call/`
This method lets you initiate an outbound call to a PSTN number or a SIP endpoint, and make simultaneous bulk calls.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Tip:** Use `<` to separate multiple destinations (max 1000). Example: `14157654321<14153464321<sip:john1234@api.vobiz.ai`
{/* Required Parameters */}
## Required Parameters
{/* Callback Parameters */}
## Callback Parameters
{/* Machine Detection Parameters */}
## Machine Detection Parameters
**Note:** For detailed machine detection documentation, see the{' '} [ Machine Detection page ](/call/machine-detection).
{/* Advanced Parameters */}
## Advanced Parameters
{/* Request Example */}
## Request Example
```
{
"from": "14155551234",
"to": "14155555678",
"answer_url": "https://example.com/answer",
"answer_method": "POST",
"ring_timeout": "30",
"time_limit": "3600",
"hangup_url": "https://example.com/hangup",
"hangup_method": "POST",
"caller_name": "John Doe",
"machine_detection": "false"
}
```
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Call/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"from": "14155551234",
"to": "14155555678",
"answer_url": "https://example.com/answer",
"answer_method": "POST"
}'
```
{/* Response Example */}
## Response Example
```
{
"api_id": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
"message": "call fired",
"call_uuid": "9834029e-58b6-11e1-b8b7-a5bd0e4e126f"
}
```
**Note:** The `call_uuid` is the unique identifier for the call.
{/* Callback Parameters Sent */}
## Parameters Sent to Callback URLs
For every voice call you make and receive, the system sends a status update to your configured callback URLs. You can read and store this information for analysis, and change the flow of ongoing calls based on the values received.
{/* Ring URL Parameters */}
### Parameters Sent to ring_url
{/* Answer URL Parameters */}
### Parameters Sent to answer_url and fallback_url
{/* Hangup URL Parameters */}
### Parameters Sent to hangup_url
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/machine-detection

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'how-it-works', title: 'How It Works', level: 2 },
{ id: 'asynchronous-detection', title: 'Asynchronous Detection', level: 2 },
{ id: 'parameters-sent', title: 'Parameters Sent to Callback', level: 2 }
];
return (
{/* Header */}
# Machine Detection
Detect answering machines on outbound calls with synchronous or asynchronous detection modes.
{/* Introduction */}
### Important: Not a Separate Endpoint  Machine detection is **NOT a separate API endpoint**. It is configured as parameters when making a call using `POST https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Call/`. This page documents the machine detection parameters and callback format.
Machine detection allows you to identify when an answering machine picks up your outbound call instead of a human. You can configure Vobiz to either hang up automatically or continue the call when a machine is detected.
**Note:** Machine detection is only supported on outbound calls initiated via the{' '} [ Make Call API ](/call/make-call). Set the `machine_detection` parameter to enable this feature.
{/* How It Works */}
## How It Works
### Synchronous Machine Detection
When you set `machine_detection=true` or `machine_detection=hangup` when making a call, Vobiz analyzes the audio after the call is answered to determine if a machine answered.
{/* Asynchronous Detection */}
## Asynchronous Machine Detection
You can take action on detecting an answering machine during a call by setting the `machine_detection_url` parameter when firing an outbound call API. Vobiz will detect an answering machine in the background and invoke the machine_detection_url with detection results.
**Benefit:** Asynchronous detection allows your application to handle the call immediately while detection happens in the background, providing better user experience.
{/* Parameters Sent */}
## Parameters Sent to machine_detection_url
When machine detection completes, Vobiz sends these parameters to your machine_detection_url:
#### Example Callback Response
```
{
"From": "+12025550000",
"Machine": true,
"To": "+12025551111",
"RequestUUID": "9834029e-58b6-11e1-b8b7-a5bd0e4e126f",
"ALegRequestUUID": "9834029e-58b6-11e1-b8b7-a5bd0e4e126f",
"CallUUID": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
"IfMachine": "continue",
"Direction": "outbound",
"ALegUUID": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
"Event": "MachineDetection",
"CallStatus": "in-progress"
}
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/transfer-call

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Transfer a Call
Transfer an in-progress call to a different URL for new call flow instructions.
{/* Introduction */}
This endpoint allows you to redirect an active call to a new XML URL. The new URL should return XML instructions that define the next steps for the call. This is useful for implementing features like call forwarding, IVR navigation, or dynamic call routing.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Note:** The call must be in an active state (in-progress) to be transferred. You can transfer both call legs independently using their respective UUIDs.
**Important:** Transfer operations interrupt the current call flow and immediately execute the XML returned from the new URL. Ensure your transfer URL is accessible and returns valid XML.
{/* HTTP Request */}
## HTTP Request
POST
POST https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Call/{`{call_uuid}`}/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz account ID (e.g., {'{Auth_ID}'})
`call_uuid`
string
Required
Unique identifier of the call to transfer
{/* Request Parameters */}
## Request Parameters
**Transfer Leg Options:**
`aleg`
Transfers only the caller (A leg) to the new URL
`bleg`
Transfers only the callee (B leg) to the new URL
`both`
Transfers both legs to their respective URLs (requires both aleg_url and bleg_url)
{/* Response */}
## Response
Returns a success message confirming the call transfer request has been initiated.
```
{
"api_id": "uuid-here",
"message": "call transferred",
"call_uuid": "call-uuid-here"
}
```
#### Response Fields
`api_id`
- Unique identifier for this API request
`message`
- Confirmation message indicating the transfer status
{/* Example Request */}
## Example Request
{/* Example 1: Transfer A Leg */}
#### Transfer A Leg (Caller) Only
```
{
"legs": "aleg",
"aleg_url": "https://yourdomain.com/transfer_instructions/",
"aleg_method": "POST"
}
```
{/* Example 2: Transfer Both Legs */}
#### Transfer Both Legs
```
{
"legs": "both",
"aleg_url": "https://example.com/transfer/aleg",
"aleg_method": "POST",
"bleg_url": "https://example.com/transfer/bleg",
"bleg_method": "POST"
}
```
{/* Example 3: cURL Example */}
#### cURL Example
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"legs": "both",
"aleg_url": "https://example.com/transfer/aleg",
"aleg_method": "POST",
"bleg_url": "https://example.com/transfer/bleg",
"bleg_method": "POST"
}'
```
#### Use Cases
•
Implement call forwarding based on IVR input
•
Route calls to different departments dynamically
•
Play announcements or collect additional information mid-call
•
Implement warm transfer scenarios with hold music
•
Change call behavior based on external triggers or events
**XML Response Example:** Your transfer URL should return XML instructions like:
{`
Please hold while we transfer your call.
+14156667890
`}
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/hangup-call

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Hang Up a Call
Terminate an active call by hanging up one or both call legs.
{/* Introduction */}
This endpoint allows you to programmatically terminate an in-progress call. You can hang up the caller (A leg), the callee (B leg), or both legs simultaneously. The call will be terminated immediately and final CDR will be generated.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Warning:** This permanently terminates the call. This action cannot be undone.
**Important:** Hanging up a call will trigger the hangup_url callback if configured when the call was initiated. This allows you to perform cleanup operations or logging.
{/* HTTP Request */}
## HTTP Request
DELETE
DELETE https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Call/{`{call_uuid}`}/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz account ID (e.g., {'{Auth_ID}'})
`call_uuid`
string
Required
Unique identifier of the call to hang up
{/* Request Parameters */}
## Request Parameters
**No Request Body Required:** This endpoint does not require any request body parameters. Simply send a DELETE request to the endpoint URL.
{/* Response */}
## Response
Returns a success message confirming the call hangup request has been processed.
```
No Content
```
**After Hangup:** The call's final CDR will show `hangup_source` as "API" and the `hangup_cause_code` will indicate a programmatic termination (typically code 16: NORMAL_CLEARING).
{/* Example Request */}
## Example Request
{/* cURL Example */}
#### cURL Example
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Use Cases
•
Terminate abandoned or idle calls to prevent billing
•
Implement time-based call limits for compliance
•
End calls based on external triggers (e.g., fraud detection)
•
Implement emergency call termination features
•
Clean up stale call sessions during maintenance
**Tip:** To retrieve the final call details after hanging up, use the{' '} [ Retrieve a Call ](/call/retrieve-call){' '} endpoint with the call UUID. The CDR will include final duration and billing information.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/retrieve-live-call

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'query-parameters', title: 'Query Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Retrieve a Live Call
Get real-time information about a currently active call, including call state and live metrics.
{/* Introduction */}
This endpoint retrieves detailed information about an in-progress call. Unlike the standard Retrieve a Call endpoint which returns finalized CDRs, this endpoint provides real-time status for active calls including current state, call flow position, and live duration metrics.
**Note:** This endpoint only returns data for calls that are currently in progress. For completed calls, use the{' '} [ Retrieve a Call ](/call/retrieve-call){' '} endpoint instead.
**Use Case:** Monitor active calls in real-time, implement live dashboards, or check call status before performing operations like transfer or hangup.
{/* HTTP Request */}
## HTTP Request
GET
/api/v1/account/{`{accountId}`}/call/{`{callUuid}`}/?status=live
#### Path Parameters
`accountId`
string
Required
Your Vobiz account ID
`callUuid`
string
Required
Unique identifier of the live call to retrieve
{/* Query Parameters */}
## Query Parameters
**Important:** The `status=live` query parameter is required. Without it, the endpoint will return the finalized CDR (if the call has ended) or a 404 error (if the call UUID doesn't exist).
{/* Response */}
## Response
Returns live call information including current status, call legs, and real-time metrics.
```
{
"api_id": "c8b427f6-58ce-11e1-86da-adf28403fe48",
"calls": [
{
"answer_time": "2014-10-15 09:03:43",
"bill_duration": null,
"billed_duration": null,
"call_direction": "outbound",
"call_duration": 180,
"call_state": "ACTIVE",
"call_uuid": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
"conference_uuid": null,
"end_time": null,
"from_number": "+14156667777",
"initiation_time": "2014-10-15 09:03:38",
"parent_call_uuid": null,
"hangup_cause_code": null,
"hangup_cause_name": null,
"hangup_source": null,
"resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Call/97ceeb52-58b6-11e1-86da-77300b68f8bb/",
"to_number": "+14156667778",
"total_amount": null,
"total_rate": null,
"stir_verification": "verified",
"stir_attestation": "A",
"source_ip": "1.1.1.1"
}
]
}
```
#### Live Call Specific Fields
`call_state`
- Current state of the call (e.g., "ACTIVE", "RINGING", "EARLY")
`call_duration`
- Live call duration in seconds since answer_time
`end_time`
- Will be null for active calls
`billed_duration`
- Will be null until call ends
`total_amount`
- Will be null until call ends and billing is calculated
`hangup_*`
- All hangup-related fields will be null for active calls
**Call State Values:**
- `RINGING` - Call is ringing, not yet answered
- `EARLY` - Early media state (e.g., ringback tone playing)
- `ACTIVE` - Call is connected and in progress
- `HELD` - Call is on hold
{/* Example Request */}
## Example Request
{/* Example 1: Basic Request */}
#### Retrieve Live Call Status
```
GET /api/v1/account/MA2025RK4E639VJFZAGV/call/97ceeb52-58b6-11e1-86da-77300b68f8bb/?status=live
Headers:
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
Content-Type: application/json
```
#### Use Cases
•
Build real-time call monitoring dashboards
•
Check call state before performing transfer or hangup operations
•
Monitor ongoing call duration for time-based triggers
•
Verify call connectivity and troubleshoot issues in real-time
•
Display live call information to supervisors or agents
•
Implement call timers and duration alerts
**Tip:** Poll this endpoint periodically to monitor live call metrics. Use the{' '} `call_duration` field to calculate current call costs in real-time by multiplying with the rate from{' '} [ Pricing ](/pricing).
**Error Response:** If the call is not currently live or has already ended, you'll receive a 404 error. In that case, use the standard{' '} [ Retrieve a Call ](/call/retrieve-call){' '} endpoint to get the finalized CDR.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/retrieve-all-live-calls

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Retrieve All Live Calls
Get a list of all ongoing call UUIDs for your account.
{/* Introduction */}
This endpoint returns an array of call UUIDs for all calls that are currently in progress on your account. This is useful for getting a quick overview of active calls without fetching full call details.
**Use Case:** Use this endpoint to monitor the number of concurrent calls on your account or to get a list of call UUIDs for batch operations.
{/* HTTP Request */}
## HTTP Request
GET
/api/v1/account/{`{accountId}`}/call/?status=live
#### Path Parameters
`accountId`
string
Required
Your Vobiz account ID
#### Query Parameters
`status`
string
Required
Must be set to "live" to retrieve ongoing calls
**Important:** The `status=live` query parameter is required to filter for active calls only.
{/* Response */}
## Response
Returns an array of call UUIDs for all ongoing calls.
```
{
"api_id": "c9527676-5839-11e1-86da-6ff39efcb949",
"calls": [
"eac94337-b1cd-499b-82d1-b39bca50dc31",
"0a70a7fb-168e-4944-a846-4f3f4d2f96f1"
]
}
```
#### Response Fields
`api_id`
- Unique identifier for this API request
`calls`
- Array of call UUIDs for all active calls
{/* Example Request */}
## Example Request
#### Retrieve All Active Calls
```
GET /api/v1/account/MA2025RK4E639VJFZAGV/call/?status=live
Headers:
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
Content-Type: application/json
```
#### Use Cases
•
Monitor concurrent call volume in real-time
•
Build live dashboards showing active call count
•
Implement call capacity alerts and monitoring
•
Get call UUIDs for batch operations (transfer, hangup)
•
Audit active calls for compliance or troubleshooting
**Next Step:** Once you have the call UUIDs, you can use them with other endpoints like{' '} [ Retrieve a Live Call ](/call/retrieve-live-call){' '} to get detailed information about each active call.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/retrieve-queued-call

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Retrieve a Queued Call
Get details of a specific call that is currently queued and waiting to be connected.
{/* Introduction */}
This endpoint retrieves information about a call that has been initiated but is not yet connected. Queued calls are waiting for the destination to answer or for resources to become available.
**What is a Queued Call?** A call is in the "queued" state when it has been initiated via the API but hasn't been answered yet. This includes calls waiting for the destination to ring or answer.
**Use Case:** Monitor calls that are waiting to be connected, track queue times, or cancel calls before they connect if needed.
{/* HTTP Request */}
## HTTP Request
GET
/api/v1/account/{`{accountId}`}/call/{`{callUuid}`}/?status=queued
#### Path Parameters
`accountId`
string
Required
Your Vobiz account ID
`callUuid`
string
Required
Unique identifier of the queued call
#### Query Parameters
`status`
string
Required
Must be set to "queued" to retrieve queued call details
**Important:** If the call is no longer queued (connected or ended), this endpoint will return a 404 error. Use the standard{' '} [ Retrieve a Call ](/call/retrieve-call){' '} endpoint for completed calls.
{/* Response */}
## Response
Returns the queued call object with basic call information.
```
{
"direction": "outbound",
"from": "15856338537",
"call_status": "queued",
"api_id": "45223222-74f8-11e1-8ea7-12313806be9a",
"to": "14154290945",
"caller_name": "+15856338537",
"call_uuid": "6653422-91b6-4716-9fad-9463daaeeec2",
"request_uuid": "6653422-91b6-4716-9fad-9463daaeeec2"
}
```
#### Response Fields
`api_id`
- Unique identifier for this API request
`call_status`
- Always "queued" for this endpoint
`call_uuid`
- Unique identifier for the call
`request_uuid`
- Request identifier
`direction`
- Call direction ("outbound" or "inbound")
`from`
- Source phone number
`to`
- Destination phone number
`caller_name`
- Caller ID name
{/* Example Request */}
## Example Request
#### Retrieve Queued Call Status
```
GET /api/v1/account/MA2025RK4E639VJFZAGV/call/6653422-91b6-4716-9fad-9463daaeeec2/?status=queued
Headers:
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
Content-Type: application/json
```
#### Use Cases
•
Monitor calls waiting to be connected
•
Track queue times and identify slow connections
•
Verify call details before connection completes
•
Cancel queued calls if needed using the hangup endpoint
•
Debug call initiation issues
**Tip:** Combine this with the{' '} [ Retrieve All Queued Calls ](/call/retrieve-all-queued-calls){' '} endpoint to monitor all pending calls on your account at once.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/retrieve-all-queued-calls

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Retrieve All Queued Calls
Get a list of all call UUIDs for calls that are currently queued and waiting to connect.
{/* Introduction */}
This endpoint returns an array of call UUIDs for all calls currently in the queued state. The maximum number of results returned per API call is 20.
**What are Queued Calls?** Calls are in the "queued" state when they have been initiated but are waiting to be connected. This includes calls waiting for the destination to answer or for available resources.
**Use Case:** Monitor queue depth, identify calls stuck in queue, or perform bulk operations on pending calls.
{/* HTTP Request */}
## HTTP Request
GET
/api/v1/account/{`{accountId}`}/call/?status=queued
#### Path Parameters
`accountId`
string
Required
Your Vobiz account ID
#### Query Parameters
`status`
string
Required
Must be set to "queued" to retrieve queued calls
**Limit:** This endpoint returns a maximum of 20 call UUIDs per request. If you have more than 20 queued calls, you may need to poll this endpoint periodically.
{/* Response */}
## Response
Returns an array of call UUIDs for all queued calls.
```
{
"api_id": "c9527676-5839-11e1-86da-6ff39efcb949",
"calls": [
"eac94337-b1cd-499b-82d1-b39bca50dc31",
"0a70a7fb-168e-4944-a846-4f3f4d2f96f1"
]
}
```
#### Response Fields
`api_id`
- Unique identifier for this API request
`calls`
- Array of call UUIDs for all queued calls (max 20)
{/* Example Request */}
## Example Request
#### Retrieve All Queued Calls
```
GET /api/v1/account/MA2025RK4E639VJFZAGV/call/?status=queued
Headers:
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
Content-Type: application/json
```
#### Use Cases
•
Monitor queue depth and detect call backlogs
•
Identify calls stuck in queue for troubleshooting
•
Build queue management dashboards
•
Cancel all queued calls in bulk during maintenance
•
Track average time calls spend in queue
**Tip:** Use the returned call UUIDs with the{' '} [ Retrieve a Queued Call ](/call/retrieve-queued-call){' '} endpoint to get detailed information about each queued call, or use the{' '} [ Hang Up a Call ](/call/hangup-call){' '} endpoint to cancel them.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/record-calls

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'features', title: 'Key Features', level: 2 },
{ id: 'operations', title: 'Available Operations', level: 2 },
{ id: 'use-cases', title: 'Common Use Cases', level: 2 },
{ id: 'best-practices', title: 'Best Practices', level: 2 }
];
return (
{/* Header */}
# Record Calls
Record specific portions of active calls with automated transcription support.
{/* Introduction */}
The Record endpoint allows you to start and stop recording specific portions of an active call. You can create multiple recordings on the same call, customize audio formats, and enable automated transcription for compliance and quality assurance.
**Important:** Call recordings are powerful tools for compliance, training, and quality assurance. Always ensure you comply with local recording consent laws and inform participants when calls are being recorded.
{/* Key Features */}
## Key Features
### Multiple Recordings
Create multiple recordings on the same call to capture specific portions or conversations.
### Format Options
Choose between MP3 and WAV formats. MP3 files are smaller and recommended for most use cases.
### Auto Transcription
Enable automated transcription with turnaround time under 5 minutes for supported durations.
### Channel Options
Record in mono or stereo. Stereo separates caller and callee into left/right channels.
### Callbacks
Receive HTTP callbacks when recordings complete with URLs to download the audio files.
### Time Limits
Set maximum recording durations to control file sizes and storage costs.
{/* Available Operations */}
## Available Operations
POST
### Start Recording
Start recording an active call with customizable format, transcription, and callback options.
DELETE
### Stop Recording
Stop an active recording on a call. Optionally specify which recording to stop.
{/* Common Use Cases */}
## Common Use Cases
•
#### Compliance & Legal
Record calls for regulatory compliance, dispute resolution, and legal documentation.
•
#### Quality Assurance
Monitor customer service quality, agent performance, and adherence to scripts.
•
#### Training & Development
Use recorded calls for agent training, onboarding, and skill development programs.
•
#### Transcription & Analysis
Generate transcripts for sentiment analysis, keyword extraction, and call analytics.
•
#### Customer Records
Maintain detailed records of customer interactions for CRM integration and history.
{/* Best Practices */}
## Best Practices
#### Use MP3 Format
MP3 files are significantly smaller than WAV files, reducing storage costs and bandwidth usage. Use MP3 unless you specifically need uncompressed audio.
#### Set Reasonable Time Limits
Configure appropriate time limits to prevent unexpectedly large files and control costs. Default is 60 seconds, adjust based on your use case.
#### Transcription Limitations
Transcription is only available for English calls with duration between 500ms and 4 hours, and file size under 2GB. Factor these limits into your application design.
#### Use Stereo for Multi-Party
For calls with multiple participants, use stereo recording to separate speakers into different channels for easier analysis and transcription.
#### Legal Compliance
Always comply with local laws regarding call recording consent. Many jurisdictions require informing all parties that the call is being recorded.
);
}

---

# Page: /call/record-calls/start-recording

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'callback-parameters', title: 'Callback Parameters', level: 2 },
{ id: 'transcription-callback', title: 'Transcription Callback', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Start Recording a Call
Begin recording an active call with customizable format, transcription, and callback options.
{/* Introduction */}
This endpoint allows you to start recording a call that is currently in progress. You can create multiple recordings on the same call, customize the audio format, enable automated transcription, and configure callbacks to be notified when the recording is complete.
**Important:** Transcription is available only in English and limited to calls with duration between 500ms and 4 hours, and file size under 2GB.
{/* HTTP Request */}
## HTTP Request
POST
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Call/{`{call_uuid}`}/Record/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz authentication ID
`call_uuid`
string
Required
Unique identifier of the call to record
{/* Request Parameters */}
## Request Parameters
**Recommendation:** Use MP3 format for smaller file sizes. Stereo recording separates caller and callee into left/right channels for easier analysis.
{/* Callback Parameters */}
## Callback URL Parameters
When the recording ends, these parameters are sent to your callback_url via HTTP POST.
{/* Transcription Callback */}
## Transcription Callback Parameters
When transcription completes, these parameters are sent to your transcription_url via HTTP POST.
**Note:** .mp3 files are smaller than .wav files. Consider using MP3 format if you see "Recording file size too large for transcription" errors.
{/* Response */}
## Response
Returns confirmation that recording has started along with a URL to access the recording.
```
{
"api_id": "uuid-here",
"message": "recording started",
"recording_id": "recording-uuid-here",
"url": "https://recordings.example.com/recording-uuid.mp3"
}
```
#### Response Fields
`api_id`
- Unique identifier for this API request
`message`
- Confirmation message
`recording_id`
- Unique identifier for this recording
`url`
- URL where the recording file will be available
{/* Example Request */}
## Example Request
#### Basic Recording
```
{
"time_limit": 120,
"file_format": "mp3"
}
```
#### Recording with Transcription
```
{
"time_limit": 60,
"file_format": "mp3",
"callback_url": "https://example.com/recording_callback",
"callback_method": "POST"
}
```
#### Stereo Recording
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Record/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"time_limit": 60,
"file_format": "mp3"
}'
```
#### Use Cases
•
Record customer service calls for quality assurance
•
Create transcripts for compliance and legal documentation
•
Capture agent-customer interactions for training
•
Record specific call segments (e.g., after IVR)
•
Archive important business conversations
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/record-calls/stop-recording

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Stop Recording a Call
Stop an active recording on a call, optionally specifying which recording to stop.
{/* Introduction */}
This endpoint allows you to stop active recordings on a call. Since a call can have multiple ongoing recordings, you can choose to stop a specific recording by providing its URL, or stop all recordings by not providing any parameters.
**Note:** When a recording is stopped, it will be finalized and made available for download. If you configured a callback_url, it will be invoked with the recording details.
{/* HTTP Request */}
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Call/{`{call_uuid}`}/Record/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz authentication ID
`call_uuid`
string
Required
Unique identifier of the call being recorded
{/* Request Parameters */}
## Request Parameters
**Default Behavior:** If you don't provide the URL parameter, all ongoing recordings on the call will be stopped. To stop only a specific recording, provide the recording URL from the start recording response.
{/* Response */}
## Response
Returns HTTP 204 No Content on success, indicating the recording(s) have been stopped.
```
HTTP Status Code: 204
```
**Note:** A 204 status code means the request was successful but there is no content to return. The recording has been stopped and will be finalized.
{/* Example Request */}
## Example Request
{/* Example 1: Stop All Recordings */}
#### Stop All Recordings
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Record/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
{/* Example 2: Stop Specific Recording */}
#### Stop Specific Recording
```
{
"URL": "http://s3.amazonaws.com/recordings_2013/48dfaf60-3b2a-11e3.mp3"
}
```
#### Use Cases
•
Stop recording when sensitive information is about to be shared
•
End recording after specific call segments (e.g., after survey)
•
Manually control recording duration based on call events
•
Stop all recordings when call is being transferred
•
Finalize recordings before maximum time limit is reached
**Tip:** After stopping a recording, you can retrieve it using the Recordings API or wait for the callback to receive the download URL.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/play-audio

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'features', title: 'Key Features', level: 2 },
{ id: 'operations', title: 'Available Operations', level: 2 },
{ id: 'use-cases', title: 'Common Use Cases', level: 2 },
{ id: 'best-practices', title: 'Best Practices', level: 2 }
];
return (
{/* Header */}
# Play Audio on Calls
Play audio files to users during active calls for notifications, music, and announcements.
{/* Introduction */}
The Play Audio endpoint allows you to play audio files to participants in an ongoing call. This is commonly used for playing hold music, automated notifications, IVR prompts, or announcements while maintaining the call connection.
**Supported Formats:** Vobiz supports .mp3 and .wav audio files. Audio files must be accessible via HTTP/HTTPS URLs.
{/* Key Features */}
## Key Features
### Multiple Audio Files
Play multiple audio files in sequence by providing comma-separated URLs.
### Call Leg Selection
Choose which participants hear the audio: caller (A leg), callee (B leg), or both.
### Loop Playback
Play audio indefinitely for hold music or continuous announcements.
### Audio Mixing
Mix playback with call audio or mute call participants during playback.
### Duration Control
Limit playback duration to control costs and user experience.
### Stop Anytime
Stop audio playback programmatically when needed.
{/* Available Operations */}
## Available Operations
POST
### Play Audio
Play an audio file or multiple files during an active call.
DELETE
### Stop Audio
Stop playing audio that is currently being played on a call.
{/* Common Use Cases */}
## Common Use Cases
•
#### Hold Music
Play music while customers wait on hold or during call transfers.
•
#### IVR Prompts
Play menu options, instructions, or navigation prompts in interactive voice systems.
•
#### Announcements
Deliver pre-recorded announcements, promotions, or important information.
•
#### Queue Notifications
Inform callers of their position in queue or estimated wait time.
•
#### Call Recording Disclaimer
Play legal disclaimers about call recording or monitoring.
{/* Best Practices */}
## Best Practices
#### Use MP3 for Efficiency
MP3 files stream faster and use less bandwidth than WAV files. Convert your audio to MP3 for better performance.
#### Host on CDN
Host your audio files on a CDN or reliable hosting service with HTTPS support for fast, secure delivery.
#### Optimize Audio Length
Keep audio files concise. Use the length parameter to limit playback duration and prevent lengthy hold times.
#### Mix Audio Thoughtfully
Set mix=false when playing important announcements to ensure participants hear them clearly without conversation interference.
#### Test Audio Quality
Always test your audio files on actual calls to ensure proper volume, clarity, and compatibility across different devices.
);
}

---

# Page: /call/play-audio/play-audio

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Play Audio on a Call
Play an audio file or multiple files during an active call.
{/* Introduction */}
This endpoint allows you to play audio files during an active call. You can play a single audio file or multiple files in sequence, control which participants hear the audio, and configure looping and mixing behavior. Vobiz supports .mp3 and .wav audio files.
**Note:** The audio files must be accessible via HTTP or HTTPS URLs. Ensure your audio hosting service has proper CORS headers configured if needed.
{/* HTTP Request */}
## HTTP Request
POST
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Call/{`{call_uuid}`}/Play/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz authentication ID
`call_uuid`
string
Required
Unique identifier of the call
{/* Request Parameters */}
## Request Parameters
**Parameter Tips:**
•
Use comma-separated URLs to play multiple files in sequence
•
Set `loop=true` for hold music
•
Set `mix=false` for important announcements
•
Use `legs=both` to play audio to all participants
{/* Response */}
## Response
Returns confirmation that audio playback has started.
```
{
"api_id": "uuid-here",
"message": "play started"
}
```
#### Response Fields
`api_id`
- Unique identifier for this API request
`message`
- Confirmation message that playback started
{/* Example Request */}
## Example Request
#### Play Single Audio File
```
{
"urls": ["https://example.com/audio/greeting.mp3"],
"length": 10,
"legs": "both",
"loop": false,
"mix": true
}
```
#### cURL Example
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Play/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"urls": ["https://example.com/audio/greeting.mp3"],
"legs": "both"
}'
```
#### Use Cases
•
Play hold music while transferring calls
•
Play IVR menu options and prompts
•
Deliver pre-recorded announcements or promotions
•
Play queue position updates or wait time estimates
•
Play legal disclaimers or recording notifications
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/play-audio/stop-audio

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Stop Playing Audio on a Call
Stop audio that is currently being played during an active call.
{/* Introduction */}
This endpoint allows you to stop audio playback that is currently playing on an active call. This is useful for ending hold music when an agent becomes available, stopping looping audio, or interrupting announcements based on user input.
**Note:** If no audio is currently playing on the call, this endpoint will return success without performing any action.
{/* HTTP Request */}
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Call/{`{call_uuid}`}/Play/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz authentication ID
`call_uuid`
string
Required
Unique identifier of the call
**No Request Body:** This endpoint does not require any request body parameters.
{/* Request Body */}
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object.
{/* Response */}
## Response
Returns HTTP 204 No Content on success.
```
HTTP Status Code: 204
```
**Success:** A 204 status code indicates the audio playback has been stopped successfully. There is no response body.
{/* Example Request */}
## Example Request
#### Stop Audio Playback
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Play/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Use Cases
•
Stop hold music when an agent becomes available
•
End looping audio based on user DTMF input
•
Interrupt announcements when call is answered
•
Stop IVR prompts when user makes a selection
•
End audio playback before transferring the call
**Tip:** Use this endpoint in conjunction with the Play Audio endpoint to create dynamic audio experiences that respond to user actions or call events.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/speak-text

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'features', title: 'Key Features', level: 2 },
{ id: 'operations', title: 'Available Operations', level: 2 },
{ id: 'use-cases', title: 'Common Use Cases', level: 2 },
{ id: 'best-practices', title: 'Best Practices', level: 2 }
];
return (
{/* Header */}
# Speak Text on Calls
Convert text to speech and speak it during active calls using advanced TTS technology.
{/* Introduction */}
The Speak Text API uses Vobiz's text-to-speech (TTS) engine to convert written text into spoken audio during ongoing calls. This allows you to deliver dynamic messages, notifications, or instructions without pre-recording audio files. Support for 29 languages and multiple voices enables global reach.
**Supported:** 29 languages with both WOMAN and MAN voices (availability varies by language). Default is English (US) with WOMAN voice.
{/* Key Features */}
## Key Features
### 29 Languages
Support for major global languages including English, Spanish, French, German, Chinese, Japanese, and more.
### Multiple Voices
Choose between WOMAN and MAN voices for most languages (availability varies).
### Dynamic Content
Generate speech on-the-fly without pre-recording, perfect for personalized messages.
### Call Leg Selection
Choose which participants hear the speech: caller, callee, or both.
### Loop Support
Repeat text indefinitely for continuous notifications or prompts.
### Audio Mixing
Mix speech with call audio or mute participants during playback.
{/* Available Operations */}
## Available Operations
POST
### Speak Text
Convert text to speech and play it during an active call with language and voice options.
DELETE
### Stop Speaking
Stop text-to-speech that is currently being spoken on a call.
{/* Common Use Cases */}
## Common Use Cases
•
#### Dynamic IVR Menus
Generate menu options and prompts based on customer data or time of day.
•
#### Personalized Greetings
Welcome callers by name or deliver customized messages based on caller ID.
•
#### Queue Updates
Announce queue position, wait times, or estimated callback times dynamically.
•
#### Multi-Language Support
Deliver messages in the caller's preferred language for global customer support.
•
#### Real-Time Notifications
Deliver account balances, order statuses, or appointment confirmations on-demand.
{/* Best Practices */}
## Best Practices
#### Keep Text Concise
Short, clear messages are easier to understand. Break long content into multiple segments if needed.
#### Use Proper Punctuation
Punctuation affects speech pacing and tone. Use periods, commas, and question marks for natural-sounding speech.
#### Test Different Voices
Try both WOMAN and MAN voices to find which works best for your use case and audience.
#### Choose Right Language
Match the language to your caller's preference for better user experience and comprehension.
#### Avoid Special Characters
Emojis and special symbols may not be pronounced correctly. Use plain text for best results.
);
}

---

# Page: /call/speak-text/speak-text

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'supported-languages', title: 'Supported Languages', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Speak Text on a Call
Convert text to speech and play it during an active call using TTS technology.
{/* Introduction */}
This endpoint allows you to convert text to speech and play it during an active call using Vobiz's text-to-speech engine. You can choose from 29 languages and multiple voice options (WOMAN and MAN) to deliver dynamic messages without pre-recording audio files.
**Note:** The default language is English (US) with WOMAN voice. Voice availability varies by language - see the supported languages table below.
{/* HTTP Request */}
## HTTP Request
POST
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Call/{`{call_uuid}`}/Speak/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz authentication ID
`call_uuid`
string
Required
Unique identifier of the call
{/* Request Parameters */}
## Request Parameters
**Parameter Tips:**
•
Keep text under 500 characters for optimal speech quality
•
Use periods and commas to control pacing and natural pauses
•
Set `mix=false` for important announcements
•
Match the language to your caller's preference for better comprehension
{/* Supported Languages */}
## Supported Languages
Vobiz supports 29 languages for text-to-speech. Voice availability (WOMAN/MAN) varies by language.
Language
Code
Available Voices
Arabic
arb
WOMAN
Chinese Mandarin
cmn-CN
WOMAN
Danish
da-DK
WOMAN, MAN
Dutch
nl-NL
WOMAN, MAN
English (Australia)
en-AU
WOMAN, MAN
English (India)
en-IN
WOMAN
English (UK)
en-GB
WOMAN, MAN
English (US)
en-US
WOMAN, MAN
English (Wales)
en-GB-WLS
WOMAN, MAN
French
fr-FR
WOMAN, MAN
French (Canadian)
fr-CA
WOMAN
German
de-DE
WOMAN, MAN
Hindi
hi-IN
WOMAN
Icelandic
is-IS
WOMAN, MAN
Italian
it-IT
WOMAN, MAN
Japanese
ja-JP
WOMAN, MAN
Korean
ko-KR
WOMAN, MAN
Norwegian
nb-NO
WOMAN
Polish
pl-PL
WOMAN, MAN
Portuguese (Brazilian)
pt-BR
WOMAN, MAN
Portuguese (European)
pt-PT
WOMAN, MAN
Romanian
ro-RO
WOMAN
Russian
ru-RU
WOMAN, MAN
Spanish (European)
es-ES
WOMAN, MAN
Spanish (US)
es-US
WOMAN, MAN
Swedish
sv-SE
WOMAN
Turkish
tr-TR
WOMAN
Welsh
cy-GB
WOMAN, MAN
Yue Chinese
yue-CN
WOMAN
**Note:** When using the MAN voice for a language that only supports WOMAN, the API will automatically fall back to the WOMAN voice.
{/* Response */}
## Response
Returns confirmation that text-to-speech has started.
```
{
"api_id": "uuid-here",
"message": "speak started"
}
```
#### Response Fields
`api_id`
- Unique identifier for this API request
`message`
- Confirmation message that text-to-speech started
{/* Example Request */}
## Example Request
#### Basic Text-to-Speech (English)
```
{
"text": "Hello, this is a test message from the text-to-speech system.",
"voice": "WOMAN",
"language": "en-US",
"legs": "both",
"loop": false,
"mix": true
}
```
#### cURL Example
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Speak/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"text": "Hello, this is a test message.",
"voice": "WOMAN",
"language": "en-US"
}'
```
#### Use Cases
•
Deliver personalized greetings using caller data
•
Announce queue position and wait times dynamically
•
Provide account information or order status updates
•
Create dynamic IVR menus based on time or context
•
Deliver multi-language support for global customers
**Tip:** Combine the Speak Text API with DTMF input capture to create interactive voice response systems that respond to user selections in real-time.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/speak-text/stop-speak

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Stop Speaking Text During a Call
Stop text-to-speech that is currently being spoken on an active call.
{/* Introduction */}
This endpoint allows you to stop text-to-speech playback that is currently active on a call. This is useful for ending looping messages when a user makes a selection, stopping announcements when an agent becomes available, or interrupting speech based on DTMF input.
**Note:** If no text-to-speech is currently playing on the call, this endpoint will return success without performing any action.
{/* HTTP Request */}
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Call/{`{call_uuid}`}/Speak/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz authentication ID
`call_uuid`
string
Required
Unique identifier of the call
**No Request Body:** This endpoint does not require any request body parameters.
{/* Request Body */}
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object.
{/* Response */}
## Response
Returns HTTP 204 No Content on success.
```
HTTP Status Code: 204
```
**Success:** A 204 status code indicates the text-to-speech has been stopped successfully. There is no response body.
{/* Example Request */}
## Example Request
#### Stop Text-to-Speech
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Speak/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Use Cases
•
Stop looping queue messages when an agent answers
•
End IVR menu announcements when user presses a DTMF key
•
Interrupt speech when transferring to a live agent
•
Stop welcome messages when call is answered
•
End promotional announcements based on user action
**Tip:** Use this endpoint in conjunction with the Speak Text endpoint to create dynamic TTS experiences that respond to user input or call events in real-time.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/dtmf

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'api-endpoint', title: 'API Endpoint', level: 2 },
{ id: 'key-features', title: 'Key Features', level: 2 },
{ id: 'use-cases', title: 'Common Use Cases', level: 2 },
{ id: 'available-operations', title: 'Available Operations', level: 2 }
];
return (
{/* Header */}
# DTMF
Send DTMF tones during active calls to automate interactions with IVR systems and other tone-based services.
{/* Introduction */}
DTMF (Dual-Tone Multi-Frequency) is the tone that's generated whenever a key is pressed in an active call. This resource allows you to send DTMF digits in an active call. The common use case for using this object is to automate sending of specific digits to a receiver in an outbound call.
**Use Case Example:** Automatically navigate IVR menus, enter access codes, or provide automated responses to phone systems without manual input.
{/* API Endpoint */}
## API Endpoint
### Base URI
https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Call/{'{call_uuid}'}/DTMF/
{/* Key Features */}
## Key Features
🎹
### All DTMF Digits
Send any DTMF digit including 0-9, *, and # characters for complete IVR navigation.
🎯
### Leg Selection
Choose which call leg (caller or callee) receives the DTMF tones for precise control.
⚡
### Real-Time Sending
Send DTMF digits instantly during active calls for immediate interaction.
🤖
### Automation Ready
Perfect for automated call flows, IVR navigation, and programmatic call control.
{/* Common Use Cases */}
## Common Use Cases
•
#### IVR Menu Navigation
Automatically navigate through IVR menus by sending the appropriate menu selections.
•
#### Access Code Entry
Enter conference codes, PIN numbers, or access codes without manual input.
•
#### Automated Survey Responses
Submit automated responses to phone surveys or feedback systems.
•
#### Account Verification
Automatically enter account numbers or verification codes during calls.
•
#### Call Control
Send control codes to phone systems that accept DTMF commands.
{/* Available Operations */}
## Available Operations
POST
Send Digits on a Call
Send DTMF digits to an active call. Specify the digits to send and which call leg should receive them.
View Documentation →
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call/dtmf/send-digits

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Send Digits on an Active Call
Send DTMF digits to an active call for automated IVR navigation and call control.
{/* Introduction */}
This endpoint lets you send DTMF digits on an active call. DTMF (Dual-Tone Multi-Frequency) tones are the sounds generated when pressing keys on a phone keypad. You can use this to automate interactions with IVR systems, enter access codes, or control phone systems programmatically.
**Note:** The call must be in an active state for DTMF digits to be sent successfully. Invalid digits or calls that have ended will result in an error.
{/* HTTP Request */}
## HTTP Request
POST
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Call/{`{call_uuid}`}/DTMF/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz authentication ID
`call_uuid`
string
Required
Unique identifier of the active call
{/* Request Parameters */}
## Request Parameters
**Parameter Tips:**
•
Only digits 0-9, *, and # are valid DTMF characters
•
The `aleg` refers to the caller (A-leg), `bleg` refers to the callee (B-leg)
•
DTMF tones are sent in the order specified in the digits string
{/* Response */}
## Response
Returns an acknowledgement that the DTMF digits were sent.
```
{
"api_id": "uuid-here",
"message": "digits sent"
}
```
#### Response Fields
`api_id`
- Unique identifier for this API request
`message`
- Confirmation message that digits were sent successfully
{/* Example Request */}
## Example Request
#### Send DTMF Digits
```
{
"digits": "1234#",
"leg": "aleg"
}
```
#### cURL Example
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/DTMF/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"digits": "1234#",
"leg": "aleg"
}'
```
#### Common Use Cases
•
Automatically navigate through IVR menu options
•
Enter PIN codes or access numbers for conference calls
•
Submit automated responses to phone surveys
•
Control phone systems that accept DTMF commands
•
Enter account numbers or verification codes
**Tip:** When automating IVR navigation, add appropriate delays between DTMF sends to allow the system time to process each input and respond with the next prompt.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /conference

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'conference-vs-mpc', title: 'Conference vs Multiparty Call', level: 2 },
{ id: 'key-features', title: 'Key Features', level: 2 },
{ id: 'conference-operations', title: 'Conference Operations', level: 2 },
{ id: 'member-operations', title: 'Member Operations', level: 2 },
{ id: 'recording-operations', title: 'Recording Operations', level: 2 }
];
return (
{/* Header */}
# Conference
Manage multi-participant conference calls with Vobiz's Conference API for traditional meeting use cases.
{/* Introduction */}
Conferences let you involve multiple participants in a single call. Using Vobiz's Conference API, you can manage ongoing and completed conferences in your account, terminate ongoing conferences, and retrieve details of an ongoing or completed conference.
### Base URL
https://api.vobiz.ai/api
### Endpoint
https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Conference/
**Authentication Required:**
- • X-Auth-ID header with your account ID (e.g., {'{Auth_ID}'})
- • X-Auth-Token header with your account Auth Token
- • Content-Type: application/json for POST requests
{/* Conference vs MPC */}
## Conference vs Multiparty Call
Vobiz offers two solutions for multi-participant calls, each optimized for different use cases:
Conference
#### Traditional Meeting Use Cases
•
**Best for:** Traditional conference calls, team meetings, webinars, group discussions
•
**Setup:** Typically initiated via XML (Conference element) during call flow
•
**Control:** Basic member controls (mute, deaf, kick, hang up)
•
**Features:** Simple recording, audio/text playback to members
Multiparty Call (MPC)
#### Advanced Contact Center Use Cases
•
**Best for:** Contact centers, sales dialers, customer support, complex call flows
•
**Setup:** API-driven with programmatic participant management
•
**Control:** Advanced controls including role-based permissions, coach mode, hold states
•
**Features:** Dual-level recording, pause/resume, participant-level recording, supervisor monitoring
**Recommendation:** Use Conference for simple multi-participant calls and meetings. Choose Multiparty Call when you need advanced control, role-based permissions, or contact center features like coach mode and supervisor monitoring.
{/* Key Features */}
## Key Features
#### Conference Management
•
Retrieve details of ongoing conferences
•
List all active conferences in your account
•
Terminate individual or all conferences
•
Monitor conference runtime and participant count
#### Member Control
•
Mute/unmute individual members or all members
•
Deaf/undeaf members to control what they hear
•
Kick members (disconnect with XML continuation)
•
Hang up members (terminate connection)
•
Play audio or text to specific members
#### Recording & Transcription
•
Start/stop recording during ongoing conferences
•
Support for MP3 and WAV file formats
•
Automatic transcription (English, under 4 hours)
•
Callback notifications for recording completion
{/* Conference Operations */}
## Conference Operations
### The Conference Object
Understand the Conference object structure with all attributes including conference name, runtime, member count, and individual member details.
View Documentation →
GET
### Retrieve a Conference
Get detailed information about a specific ongoing conference including all active members and their states.
View Documentation →
GET
### List All Conferences
Retrieve a list of all ongoing conferences in your account with their names.
View Documentation →
DELETE
### Hang Up a Conference
Terminate a specific conference and disconnect all participants.
View Documentation →
DELETE
### Hang Up All Conferences
Terminate all ongoing conferences in your account simultaneously.
View Documentation →
{/* Member Operations */}
## Member Operations
Control individual conference members or perform actions on all members simultaneously. Most operations support targeting by member_id, comma-separated list of IDs, or "all" for bulk operations.
### Conference Members
Explore all member control operations including mute, deaf, kick, hang up, and audio/text playback features.
View All Member Operations →
{/* Recording Operations */}
## Recording Operations
Record conference calls with automatic transcription support. Recordings can be started and stopped during ongoing conferences for flexible compliance and documentation needs.
### Conference Recording
Learn about conference recording features including transcription, callback events, and file format options.
View Recording Documentation →
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /conference/conference-object

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'member-attributes', title: 'Member Attributes', level: 2 },
{ id: 'example', title: 'Example Response', level: 2 }
];
return (
{/* Header */}
# The Conference Object
Understand the structure and attributes of the Conference object returned by the Vobiz API.
{/* Introduction */}
The Conference object contains information about an ongoing conference including its runtime, participant count, and detailed information about each member currently in the conference.
**Note:** The Conference object is returned when you retrieve a specific conference or list all conferences. It provides a complete snapshot of the conference state at the time of the request.
{/* Conference-Level Attributes */}
## Conference Attributes
{/* Member Attributes */}
## Member Attributes
Each member object in the `members` array contains the following attributes:
**Member State Indicators:**
•
`muted: true` - Member cannot be heard by others
•
`deaf: true` - Member cannot hear others
•
`muted: true, deaf: true` - Member is isolated from the conference
{/* Example Response */}
## Example Response
Here's an example Conference object with one active member:
```
{
"conference_name": "My Conf Room",
"conference_run_time": "590",
"conference_member_count": "1",
"members": [
{
"muted": false,
"member_id": "17",
"deaf": false,
"from": "1456789903",
"to": "1677889900",
"caller_name": "John",
"direction": "inbound",
"call_uuid": "acfbf0b5-12e0-4d74-85f7-fce15f8f07ec",
"join_time": "590"
}
]
}
```
**Understanding the Example:**
•
Conference "My Conf Room" has been running for 590 seconds (~9.8 minutes)
•
Currently has 1 active member (John)
•
John is not muted or deaf - full two-way audio
•
John joined via inbound call from number 1456789903
•
John has been in the conference for 590 seconds (joined when conference started)
#### Multiple Members Example
```
{
"conference_name": "Team Meeting",
"conference_run_time": "1200",
"conference_member_count": "3",
"members": [
{
"muted": false,
"member_id": "45",
"deaf": false,
"from": "14155551234",
"to": "14155559999",
"caller_name": "Alice Johnson",
"direction": "inbound",
"call_uuid": "a1b2c3d4-1234-5678-90ab-cdef12345678",
"join_time": "1200"
},
{
"muted": true,
"member_id": "46",
"deaf": false,
"from": "14155555678",
"to": "14155559999",
"caller_name": "",
"direction": "outbound",
"call_uuid": "b2c3d4e5-2345-6789-01bc-def123456789",
"join_time": "900"
},
{
"muted": false,
"member_id": "47",
"deaf": false,
"from": "14155556789",
"to": "14155559999",
"caller_name": "Bob Smith",
"direction": "inbound",
"call_uuid": "c3d4e5f6-3456-7890-12cd-ef1234567890",
"join_time": "300"
}
]
}
```
**Analysis:**
•
**Alice (member 45):** Joined when conference started, speaking
•
**Unnamed (member 46):** Called outbound 5 minutes after start, currently muted
•
**Bob (member 47):** Joined 15 minutes after start, speaking
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /conference/retrieve-conference

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Retrieve a Conference
Get detailed information about a specific ongoing conference including all active members.
{/* Introduction */}
This endpoint retrieves the details of a particular conference by its name. The response includes the conference runtime, member count, and detailed information about each member currently in the conference.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Use Cases:** Monitor active conferences, check participant status, verify member states (muted/deaf), track join times, and gather call UUIDs for further operations.
{/* HTTP Request */}
## HTTP Request
GET
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Conference/{`{conference_name}`}/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz account ID (e.g., {'{Auth_ID}'})
`conference_name`
string
Required
Name of the conference to retrieve
**No request body needed.** Simply use the GET method with the conference name in the URL path.
{/* Response */}
## Response
Returns the details of the conference associated with the name specified, including all active members.
```
{
"conference_name": "My Conf Room",
"conference_run_time": "590",
"conference_member_count": "1",
"members": [
{
"muted": false,
"member_id": "17",
"deaf": false,
"from": "1456789903",
"to": "1677889900",
"caller_name": "John",
"direction": "inbound",
"call_uuid": "acfbf0b5-12e0-4d74-85f7-fce15f8f07ec",
"join_time": "590"
}
],
"api_id": "816e903e-58c4-11e1-86da-adf28403fe48"
}
```
#### Response Fields
`conference_name`
- Name of the conference
`conference_run_time`
- Duration in seconds since conference started
`conference_member_count`
- Number of active members
`members`
- Array of member objects with detailed information
`api_id`
- Unique identifier for this API request
**Member Information:** Each member object includes their ID, mute/deaf status, caller details, direction (inbound/outbound), call UUID, and join time. See The Conference Object documentation for detailed attribute descriptions.
{/* Example Request */}
## Example Request
#### Retrieve Conference by Name
```
curl -X GET https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/My%20Conf%20Room/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
Note: Conference names with spaces must be URL-encoded (space becomes %20).
#### Response with Multiple Members
```
{
"conference_name": "Team Meeting",
"conference_run_time": "1200",
"conference_member_count": "3",
"members": [
{
"muted": false,
"member_id": "45",
"deaf": false,
"from": "14155551234",
"to": "14155559999",
"caller_name": "Alice Johnson",
"direction": "inbound",
"call_uuid": "a1b2c3d4-1234-5678-90ab-cdef12345678",
"join_time": "1200"
},
{
"muted": true,
"member_id": "46",
"deaf": false,
"from": "14155555678",
"to": "14155559999",
"caller_name": "",
"direction": "outbound",
"call_uuid": "b2c3d4e5-2345-6789-01bc-def123456789",
"join_time": "900"
},
{
"muted": false,
"member_id": "47",
"deaf": false,
"from": "14155556789",
"to": "14155559999",
"caller_name": "Bob Smith",
"direction": "inbound",
"call_uuid": "c3d4e5f6-3456-7890-12cd-ef1234567890",
"join_time": "300"
}
],
"api_id": "816e903e-58c4-11e1-86da-adf28403fe48"
}
```
**Common Use Cases:**
•
**Monitor conference status:** Check how long a conference has been running
•
**Verify participants:** See who is currently in the conference
•
**Check member states:** Identify which members are muted or deaf
•
**Track join times:** Determine when each participant joined
•
**Get call UUIDs:** Retrieve call UUIDs for further call operations
•
**Dashboard display:** Show real-time conference information in admin panels
**Best Practices:**
•
URL-encode conference names that contain spaces or special characters
•
Poll this endpoint periodically for dashboard updates (recommended: every 5-10 seconds)
•
Cache member_ids for quick access when performing member operations
•
Use call_uuid to correlate conference members with CDR records
•
Handle 404 responses gracefully - conference may have ended between requests
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /conference/hang-up-conference

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Hang Up a Conference
Terminate a specific conference and disconnect all participants.
{/* Introduction */}
This endpoint terminates a specific conference identified by its name. All participants in the conference will be disconnected immediately.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Important:** This action immediately disconnects all participants and cannot be undone. The conference will end completely and cannot be resumed.
**Use Cases:** End scheduled meetings on time, terminate conferences due to emergencies, clean up abandoned conference rooms, administrative conference management.
{/* HTTP Request */}
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Conference/{`{conference_name}`}/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz account ID (e.g., {'{Auth_ID}'})
`conference_name`
string
Required
Name of the conference to terminate
**No request body needed.** Simply use the DELETE method with the conference name in the URL path.
{/* Request Body */}
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object.
{/* Response */}
## Response
Returns an acknowledgement that the conference has been terminated.
```
HTTP Status Code: 204
```
**What Happens:**
1.
All participants are immediately disconnected from the conference
2.
The conference room is terminated and cannot be rejoined
3.
Any ongoing recordings are stopped and finalized
4.
The conference no longer appears in the active conferences list
**Note:** If the conference has already ended or doesn't exist, you may receive an error response. Always handle 404 errors gracefully in your application.
{/* Example Request */}
## Example Request
#### Hang Up Conference by Name
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/My%20Conf%20Room/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
Remember to URL-encode conference names with spaces or special characters.
**Common Use Cases:**
•
**Scheduled end time:** Automatically terminate meetings at their scheduled end time
•
**Emergency termination:** End conferences immediately due to security or policy violations
•
**Admin control:** Allow moderators to end conferences from admin panels
•
**Cleanup:** Terminate abandoned conference rooms to free resources
•
**Time limits:** Enforce maximum conference duration limits
•
**Workflow triggers:** End conference when specific conditions are met
**Best Practices:**
•
Notify participants before hanging up a conference (e.g., play announcement first)
•
Verify conference exists before attempting to hang up (use Retrieve Conference first)
•
Log conference terminations for audit trails and analytics
•
Implement confirmation dialogs in admin UIs before terminating active conferences
•
Handle errors gracefully - conference may have already ended naturally
•
Consider using Kick Member instead if you only need to remove specific participants
**Alternative: Hang Up All Conferences**
If you need to terminate all conferences at once (e.g., for system maintenance), use the [ Hang Up All Conferences ](/conference/hang-up-all-conferences) endpoint instead.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /conference/retrieve-all-conferences

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# List All Conferences
Retrieve a list of all ongoing conferences in your account.
{/* Introduction */}
This endpoint retrieves a list of all ongoing conferences for your account and returns their names. You can then use these names to retrieve detailed information about specific conferences or perform operations on them.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Use Cases:** Dashboard displays showing active conferences, monitoring conference activity, generating conference reports, administrative oversight, system health checks.
{/* HTTP Request */}
## HTTP Request
GET
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Conference/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz account ID (e.g., {'{Auth_ID}'})
**No request body or query parameters needed.** Simply use the GET method on the base conference endpoint.
{/* Response */}
## Response
Returns the names of all ongoing conferences associated with the account.
```
{
"conferences": [
"Team Meeting",
"Sales Call",
"Customer Support Conference"
],
"api_id": "816e903e-58c4-11e1-86da-adf28403fe48"
}
```
```
{
"conferences": [],
"api_id": "816e903e-58c4-11e1-86da-adf28403fe48"
}
```
#### Response Fields
`conferences`
- Array of conference names currently active. Empty array if no conferences are running.
`api_id`
- Unique identifier for this API request
**Note:** The response only includes conference names, not detailed information. To get member counts, runtime, and participant details, use the Retrieve a Conference endpoint for each conference name.
{/* Example Request */}
## Example Request
#### List All Active Conferences
```
curl -X GET https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Typical Workflow: Get Conference Details
Use this endpoint to discover conference names, then retrieve detailed information for each:
```
# Get list of conference names
curl -X GET https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
# Response: {"conferences": ["Team Meeting", "Sales Call"]}
```
```
# Get details for "Team Meeting"
curl -X GET https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/Team%20Meeting/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
# Response includes member count, runtime, and all participants
```
**Common Use Cases:**
•
**Dashboard overview:** Display all active conferences in admin panel
•
**System monitoring:** Track number of concurrent conferences
•
**Resource management:** Identify conferences to free up capacity
•
**Reporting:** Generate usage statistics and activity reports
•
**Cleanup operations:** Find abandoned or long-running conferences
•
**Billing:** Track active conference usage for billing purposes
**Best Practices:**
•
Poll this endpoint periodically for dashboard updates (recommended: every 10-30 seconds)
•
Cache results to reduce API calls - refresh only when needed
•
Handle empty conference arrays gracefully (no active conferences is normal)
•
Iterate through results to get detailed info only when needed
•
Implement rate limiting to avoid excessive API calls
•
Use WebSockets or webhooks for real-time updates instead of frequent polling
**Example: Dashboard Implementation**
```
// Fetch all active conferences
async function getActiveConferences() {
const response = await fetch(
'https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/',
{
headers: {
'Authorization': 'Bearer {access_token}',
'X-Auth-ID': '{auth_id}'
}
}
);
const data = await response.json();
return data.conferences; // Array of conference names
}
// Get details for each conference
async function getConferenceDetails(conferenceName) {
const encodedName = encodeURIComponent(conferenceName);
const response = await fetch(
\`https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/\${encodedName}/\`,
{
headers: {
'Authorization': 'Bearer {access_token}',
'X-Auth-ID': '{auth_id}'
}
}
);
return await response.json();
}
// Update dashboard every 15 seconds
setInterval(async () => {
const conferences = await getActiveConferences();
console.log(\`Active conferences: \${conferences.length}\`);
// Get details for each
for (const name of conferences) {
const details = await getConferenceDetails(name);
console.log(\`\${name}: \${details.conference_member_count} members\`);
}
}, 15000);
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /conference/hang-up-all-conferences

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 }
];
return (
{/* Header */}
# Hang Up All Conferences
Terminate all ongoing conferences in your account simultaneously.
{/* Introduction */}
This API lets you hang up all ongoing conferences running on your account at once. All participants across all conferences will be disconnected immediately.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**⚠️ Warning:** This is a destructive operation that affects ALL active conferences in your account. All participants in every conference will be disconnected immediately and cannot rejoin. This action cannot be undone.
**Use Cases:** System maintenance, emergency shutdown, end-of-day cleanup, security incidents, platform-wide service termination, testing/development environment resets.
{/* HTTP Request */}
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Conference/
#### Path Parameters
`auth_id`
string
Required
Your Vobiz account ID (e.g., {'{Auth_ID}'})
**No request body needed.** Simply use the DELETE method on the base conference endpoint to terminate all conferences.
{/* Request Body */}
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object.
{/* Response */}
## Response
Returns a success status code indicating all conferences have been terminated.
```
HTTP Status Code: 204
```
**What Happens:**
1.
All active conferences across your account are terminated simultaneously
2.
Every participant in every conference is immediately disconnected
3.
All conference rooms are closed and cannot be rejoined
4.
Any ongoing recordings across all conferences are stopped and finalized
5.
The conferences list becomes empty
**Success:** A 204 status code indicates all conferences were successfully terminated. If there were no active conferences, this still returns 204.
{/* Example Request */}
## Example Request
#### Hang Up All Conferences
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Common Use Cases:**
•
**System maintenance:** Clear all conferences before scheduled maintenance window
•
**Emergency shutdown:** Immediately terminate all services during critical incidents
•
**End of day cleanup:** Automatically close all conferences at business closing time
•
**Testing environment:** Reset test environment by clearing all active conferences
•
**Security response:** Terminate all conferences during security breach response
•
**Resource management:** Force-close abandoned conferences consuming resources
**⚠️ Important Warnings:**
•
**No undo:** This operation cannot be reversed - terminated conferences cannot be restored
•
**No selective termination:** ALL conferences are affected, not just specific ones
•
**Immediate effect:** Disconnection happens instantly without warning to participants
•
**Production caution:** Use extreme caution in production environments
•
**No participant notification:** Participants receive no advance notice
**Best Practices:**
•
**List first:** Call List All Conferences before terminating to know what will be affected
•
**Notify participants:** Send announcements to conferences before terminating (if time allows)
•
**Implement confirmation:** Require double-confirmation in UI before executing
•
**Log operations:** Always log when this endpoint is called and by whom
•
**Restrict access:** Limit this API call to admin-level accounts only
•
**Schedule carefully:** Use during off-peak hours when possible
•
**Alternative approach:** Consider terminating conferences individually when selective control is needed
**Example: Safe Implementation with Confirmation**
```
async function hangUpAllConferences() {
// Step 1: Get list of active conferences
const listResponse = await fetch(
'https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/',
{
headers: {
'Authorization': 'Bearer {access_token}',
'X-Auth-ID': '{auth_id}'
}
}
);
const { conferences } = await listResponse.json();
// Step 2: Show confirmation
if (conferences.length === 0) {
console.log('No active conferences to terminate');
return;
}
const confirmed = confirm(
\`WARNING: This will terminate \${conferences.length} active conferences.\\n\` +
\`Conferences: \${conferences.join(', ')}\\n\\n\` +
'All participants will be disconnected immediately.\\n' +
'This action cannot be undone.\\n\\n' +
'Are you sure you want to continue?'
);
if (!confirmed) {
console.log('Operation cancelled by user');
return;
}
// Step 3: Log the operation
console.log('Terminating all conferences:', conferences);
// Step 4: Execute termination
const response = await fetch(
'https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/',
{
method: 'DELETE',
headers: {
'Authorization': 'Bearer {access_token}',
'X-Auth-ID': '{auth_id}'
}
}
);
if (response.status === 204) {
console.log(\`Successfully terminated \${conferences.length} conferences\`);
}
}
// Usage: Call with extreme caution
// hangUpAllConferences();
```
**Alternative: Selective Termination**
If you need more control, consider terminating conferences individually using the [ Hang Up a Conference ](/conference/hang-up-conference) endpoint. This allows you to selectively terminate specific conferences while leaving others active.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /conference/members

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'member-targeting', title: 'Member Targeting', level: 2 },
{ id: 'control-operations', title: 'Control Operations', level: 2 },
{ id: 'audio-operations', title: 'Audio & Text Operations', level: 2 }
];
return (
{/* Header */}
# Conference Members
Control individual conference members with mute, deaf, kick, hang up, and audio/text playback operations.
{/* Introduction */}
This resource lets you perform actions on members of a conference. You can control audio states (mute/deaf), remove participants (kick/hang up), and play audio or text to specific members.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
{/* Member Targeting */}
## Member Targeting
Most member operations support flexible targeting allowing you to act on individual members, multiple members, or all members at once:
`member_id`
Single Member
Target a specific member by their member_id (e.g., "17"). Only that member is affected.
/Member/17/Mute/
`comma-separated list`
Multiple Members
Target multiple specific members by providing a comma-separated list of member IDs.
/Member/17,45,82/Mute/
`"all"`
All Members
Use the string "all" to target every member in the conference simultaneously.
/Member/all/Mute/
**Note:** Member IDs can be retrieved from the conference details when you call the Retrieve a Conference endpoint. Each member has a unique ID within that conference.
{/* Control Operations */}
## Control Operations
DELETE
### Hang Up a Member
Immediately disconnect a member from the conference. The call is terminated completely.
View Documentation →
POST
### Kick a Member
Disconnect a member but allow XML flow continuation. Member can hear next XML elements after disconnection.
View Documentation →
POST
### Mute a Member
Mute a member's audio so other participants cannot hear them. Member can still hear the conference.
View Documentation →
DELETE
### Unmute a Member
Unmute a previously muted member allowing them to be heard by other participants again.
View Documentation →
POST
### Deaf a Member
Prevent a member from hearing conference audio. They can still speak but won't hear others.
View Documentation →
DELETE
### Undeaf a Member
Restore hearing for a deafened member allowing them to hear conference audio again.
View Documentation →
{/* Audio & Text Operations */}
## Audio & Text Operations
POST
### Play Audio to a Member
Play audio files to specific conference members. Useful for announcements or hold music.
View Documentation →
DELETE
### Stop Audio to a Member
Stop ongoing audio playback for specific members.
View Documentation →
POST
### Speak Text to a Member
Convert text to speech and play it to specific conference members using TTS engine.
View Documentation →
DELETE
### Stop Speaking to a Member
Stop ongoing text-to-speech playback for specific members.
View Documentation →
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /conference/members/hang-up-member

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Hang Up a Member
Disconnect a member from the conference by terminating their call.
This method lets you hang up a particular member of a conference. The member to be disconnected needs to be identified using the member_id.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Note:** This completely terminates the member's call. For disconnecting while allowing XML flow continuation, use the Kick Member endpoint instead.
## HTTP Request
DELETE
/api/v1/account/{`{auth_id}`}/conference/{`{conference_name}`}/member/{`{member_id}`}/
The member_id can be: a specific member_id, comma-separated list, or "all" to hang up all members.
{/* Request Body */}
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object.
## Response
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Hang Up All Members
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/all/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
);
}

---

# Page: /conference/members/kick-member

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Kick a Member
Disconnect a member from a conference while allowing XML flow continuation.
This method lets you disconnect a member in a conference. When the member is disconnected, the next action to be performed depends on the next element in the XML.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**XML Example:** If the XML code below starts the conference, Vobiz will play the text in the Speak tag after the member is disconnected.
```
MyConference
You have been disconnected from the conference
```
**Difference from Hang Up:** Kick allows XML continuation, while Hang Up terminates the call completely.
## HTTP Request
POST
/api/v1/account/{`{auth_id}`}/conference/{`{conference_name}`}/member/{`{member_id}`}/kick/
The member_id can be: a specific member_id, comma-separated list, or "all" to kick all members.
{/* Request Body */}
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object.
## Response
```
{
"message": "kicked",
"member_id": "10",
"api_id": "2867b6e2-58c3-11e1-86da-adf28403fe48"
}
```
## Examples
#### Kick Specific Member
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10/Kick/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{}'
```
#### Kick All Members
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/all/Kick/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{}'
```
**Use Case:** Kick is useful when you want to remove a member but play them an announcement or redirect them to another action via XML.
);
}

---

# Page: /conference/members/mute-member

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Mute a Member
Mute conference members so other participants cannot hear them.
This API lets you mute members of a conference. Audio from their device will be muted, and other members in the conference will not be able to hear the caller.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Note:** Muted members can still hear other participants. They just cannot be heard by others. To prevent a member from hearing, use the Deaf Member endpoint.
## HTTP Request
POST
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Conference/{`{conference_name}`}/Member/{`{member_id}`}/Mute/
The member_id can be: a specific member_id, comma-separated list, or "all" to mute all members.
{/* Request Body */}
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object.
## Response
```
{
"message": "muted",
"member_id": "10",
"api_id": "2867b6e2-58c3-11e1-86da-adf28403fe48"
}
```
## Examples
#### Mute Specific Member
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10/Mute/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json"
```
#### Mute All Members
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/all/Mute/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json"
```
**Common Use Cases:**
- • Mute all members during presenter mode
- • Silence disruptive participants
- • Temporary mute during announcements
- • Q&A session control
);
}

---

# Page: /conference/members/unmute-member

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Unmute a Member
Restore audio from previously muted members so other participants can hear them again.
This API allows you to unmute members who were previously muted. Once unmuted, the audio from their device will be transmitted to other participants in the conference.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Note:** This operation reverses the mute state. If a member was never muted, this call will have no effect but will still return success.
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Conference/{`{conference_name}`}/Member/{`{member_id}`}/Mute/
The member_id can be: a specific member_id, comma-separated list, or "all" to unmute all members.
{/* Request Body */}
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object.
## Response
```
{
"message": "unmuted",
"member_id": ["10"],
"api_id": "4d944694-58c4-11e1-86da-adf28403fe48"
}
```
## Examples
#### Unmute Specific Member
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10/Mute/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Unmute Multiple Members
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10,15,22/Mute/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Unmute All Members
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/all/Mute/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Common Use Cases:**
- • End presenter mode and allow audience participation
- • Restore audio after temporary mute during announcements
- • Enable Q&A session participation
- • Unmute after disruptive behavior has ceased
);
}

---

# Page: /conference/members/deaf-member

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Deaf a Member
Prevent conference members from hearing other participants while remaining connected.
This API lets you deaf members of a conference. When deafened, members will not be able to hear audio from other participants, but they remain connected to the conference and can still be heard by others.
**Deaf vs Mute:**
- • **Deaf:** Member cannot hear others (incoming audio blocked)
- • **Mute:** Others cannot hear the member (outgoing audio blocked)
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Note:** Deafened members can still speak and be heard by others. To prevent them from being heard, use the Mute Member endpoint.
## HTTP Request
POST
/api/v1/account/{`{auth_id}`}/conference/{`{conference_name}`}/member/{`{member_id}`}/deaf/
The member_id can be: a specific member_id, comma-separated list, or "all" to deaf all members.
{/* Request Body */}
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object.
## Response
```
{
"message": "deaf",
"member_id": "10",
"api_id": "5a3c8c80-58c4-11e1-86da-adf28403fe48"
}
```
## Examples
#### Deaf Specific Member
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10/Deaf/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{}'
```
#### Deaf All Members
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/all/Deaf/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{}'
```
**Common Use Cases:**
- • Create listen-only mode for webinar attendees
- • Prevent feedback loops during audio playback
- • Isolate members for private whisper conversations
- • Testing scenarios where member should not hear conference
);
}

---

# Page: /conference/members/undeaf-member

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Undeaf a Member
Restore audio reception for previously deafened members so they can hear other participants again.
This API allows you to undeaf members who were previously deafened. Once undeafened, members will be able to hear audio from other participants in the conference again.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Note:** This operation reverses the deaf state. If a member was never deafened, this call will have no effect but will still return success.
## HTTP Request
DELETE
/api/v1/account/{`{auth_id}`}/conference/{`{conference_name}`}/member/{`{member_id}`}/deaf/
The member_id can be: a specific member_id, comma-separated list, or "all" to undeaf all members.
{/* Request Body */}
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object.
## Response
```
{
"message": "undeaf",
"member_id": ["10"],
"api_id": "66d7c41e-58c4-11e1-86da-adf28403fe48"
}
```
## Examples
#### Undeaf Specific Member
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10/Deaf/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Undeaf Multiple Members
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10,15,22/Deaf/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Undeaf All Members
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/all/Deaf/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Common Use Cases:**
- • Switch from listen-only to interactive mode
- • Enable Q&A session after presentation
- • Restore full audio after audio playback completes
- • Re-enable conference participation after isolation
);
}

---

# Page: /conference/members/play-audio

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Play Audio to a Member
Play audio files to specific conference members without other participants hearing.
This API allows you to play an audio file to one or more members of a conference. Only the specified members will hear the audio, while other participants remain unaffected.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Privacy:** Audio is played exclusively to the targeted member(s). Other conference participants will not hear the audio being played.
**Supported Formats:** MP3, WAV. Audio files must be accessible via HTTPS URL.
## HTTP Request
POST
/api/v1/account/{`{auth_id}`}/conference/{`{conference_name}`}/member/{`{member_id}`}/play/
The member_id can be: a specific member_id, comma-separated list, or "all" to play audio to all members.
## Request Parameters
## Response
```
{
"message": "play started",
"api_id": "7a5e9f0a-58c4-11e1-86da-adf28403fe48",
"member_id": ["10"]
}
```
## Examples
#### Play Audio to Specific Member
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10/Play/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{"url":"https://example.com/audio/welcome.mp3"}'
```
#### Play Audio to Multiple Members
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10,15,22/Play/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{"url":"https://example.com/audio/announcement.mp3"}'
```
#### Play Audio to All Members
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/all/Play/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{"url":"https://example.com/audio/broadcast.mp3"}'
```
**Common Use Cases:**
- • Play hold music while waiting
- • Deliver private announcements to specific members
- • Play instructions or prompts during the conference
- • Broadcast alerts or notifications to all participants
);
}

---

# Page: /conference/members/stop-audio

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Stop Playing Audio to a Member
Stop audio playback that is currently playing to conference members.
This API allows you to stop audio that is currently being played to one or more members of a conference. This is useful for interrupting audio playback before it completes naturally.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Note:** If no audio is currently playing to the specified member(s), this call will have no effect but will still return success.
## HTTP Request
DELETE
/api/v1/account/{`{auth_id}`}/conference/{`{conference_name}`}/member/{`{member_id}`}/play/
The member_id can be: a specific member_id, comma-separated list, or "all" to stop audio for all members.
{/* Request Body */}
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object.
## Response
```
{
"message": "play stopped",
"member_id": ["10"],
"api_id": "8b6fa2b8-58c4-11e1-86da-adf28403fe48"
}
```
## Examples
#### Stop Audio for Specific Member
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10/Play/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Stop Audio for Multiple Members
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/10,15,22/Play/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Stop Audio for All Members
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Member/all/Play/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Common Use Cases:**
- • Stop hold music when participant becomes active
- • Interrupt announcements for urgent updates
- • Cancel audio playback when member presses DTMF key
- • Stop broadcast messages early
);
}

---

# Page: /conference/recording

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'recording-features', title: 'Recording Features', level: 2 },
{ id: 'available-operations', title: 'Available Operations', level: 2 },
{ id: 'best-practices', title: 'Best Practices', level: 2 }
];
const operations = [
{
name: 'Start Recording',
href: '/conference/recording/start-recording',
method: 'POST',
description: 'Start recording a conference with optional transcription and file format settings.'
},
{
name: 'Stop Recording',
href: '/conference/recording/stop-recording',
method: 'DELETE',
description: 'Stop an active conference recording and retrieve the recording URL.'
}
];
return (
# Conference Recording
Record conference calls with optional transcription and custom file formats.
Conference Recording allows you to capture audio from your conference calls for compliance, training, or archival purposes. You can start and stop recordings dynamically during a conference, and optionally enable real-time transcription.
**Important:** Recording can be started at any time during the conference and will capture audio from all participants until explicitly stopped or the conference ends.
## Recording Features
#### Multi-Track Recording   Record all conference participants in a single mixed audio file.
#### Transcription   Enable automatic speech-to-text transcription with timestamps.
#### File Formats   Choose from MP3 or WAV format for your recording output.
#### Secure Storage   Recordings are stored securely and accessible via HTTPS URLs.
## Available Operations
{operations.map((operation) => (
{operation.method}
### {operation.name}
{operation.description}
View Documentation →
))}
## Best Practices
#### 1. Legal Compliance
Ensure you have consent from all participants before recording. Laws vary by jurisdiction. Consider playing an announcement at the start of recording.
#### 2. Storage Management
Download and archive recordings to your own storage system. Recording URLs may have expiration policies depending on your account settings.
#### 3. Quality Settings
Use WAV format for highest quality, MP3 for smaller file sizes. Enable transcription for searchability and accessibility.
#### 4. Error Handling
Always verify recording has started successfully before proceeding. Handle cases where recording fails to start or stops unexpectedly.
**Tip:** You can retrieve recording details and download URLs from the Call Detail Records (CDR) API after the conference ends.
);
}

---

# Page: /conference/recording/start-recording

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Start Conference Recording
Begin recording a conference call with customizable settings and optional transcription.
This API allows you to start recording an active conference. The recording will capture audio from all participants and can optionally generate a transcription.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Recording Behavior:** Once started, the recording continues until explicitly stopped or until the conference ends. Multiple start requests will return an error if recording is already active.
**Legal Notice:** Ensure you comply with local recording consent laws. Consider playing an announcement to participants before starting the recording.
## HTTP Request
POST
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Conference/{`{conference_name}`}/Record/
## Request Parameters
## Response
```
{
"message": "conference recording started",
"api_id": "b0e8d7f2-58c4-11e1-86da-adf28403fe48",
"recording_id": "rec_abc123def456",
"url": "https://s3.amazonaws.com/recordings/rec_abc123def456.mp3"
}
```
## Examples
#### Start Basic Recording
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Record/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json"
```
#### Start Recording with WAV Format
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Record/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{"file_format":"wav"}'
```
#### Start Recording with Callback
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Record/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"file_format": "mp3",
"recording_callback_url": "https://yourserver.com/recording-complete",
"recording_callback_method": "POST"
}'
```
**Recording Callback:**
When recording completes, your callback URL will receive a notification with the recording details:
```
{
"conference_name": "MyConf",
"recording_id": "rec_abc123def456",
"recording_url": "https://s3.amazonaws.com/recordings/rec_abc123def456.mp3",
"recording_duration": 1200,
"file_format": "mp3"
}
```
**Best Practices:**
- • Store the recording_id for later retrieval
- • Use WAV for archival quality, MP3 for smaller file sizes
- • Secure your transcription callback URL with authentication
- • Download recordings to your own storage for long-term retention
);
}

---

# Page: /conference/recording/stop-recording

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Stop Conference Recording
Stop an active conference recording and retrieve the recording file URL.
This API allows you to stop an active conference recording. Once stopped, the recording is finalized and becomes available for download.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Processing Time:** After stopping, the recording file may take a few moments to be fully processed and available at the provided URL. The file will remain accessible according to your account retention policy.
**Note:** If no recording is active for the specified conference, this call will return an error. Recordings are also automatically stopped when a conference ends.
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Conference/{`{conference_name}`}/Record/
## Request Body
```
{}
```
No request body parameters required. Send an empty JSON object or omit the body.
## Response
```
HTTP Status Code: 204
```
**Success:** A 204 No Content status indicates the recording was successfully stopped. The recording file will be available at the URL provided when you started the recording, or via the recording_callback_url if configured.
## Examples
#### Stop Conference Recording
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/MyConf/Record/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### JavaScript Example - Stop Recording
```
async function stopRecording(conferenceName) {
const response = await fetch(
\`https://api.vobiz.ai/api/v1/Account/{auth_id}/Conference/\${conferenceName}/Record/\`,
{
method: 'DELETE',
headers: {
'X-Auth-ID': '{auth_id}',
'X-Auth-Token': '{access_token}'
}
}
);
if (response.status === 204) {
console.log('Recording stopped successfully');
// Recording file will be available via callback URL
// or can be retrieved from your recording storage
}
}
stopRecording('MyConf');
```
**Best Practices:**
- • Download recordings immediately to your own storage
- • Store recording_id in your database for future reference
- • Implement retry logic for download failures
- • Verify recording duration matches expected conference length
**Callback Notification:** If you configured a recording_callback_url when starting the recording, you'll receive a POST request with the recording details once processing is complete.
);
}

---

# Page: /endpoint

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'what-is-endpoint', title: 'What is an Endpoint?', level: 2 },
{ id: 'api-endpoint', title: 'API Endpoint', level: 2 },
{ id: 'available-operations', title: 'Available Operations', level: 2 },
{ id: 'sip-configuration', title: 'SIP Configuration', level: 2 },
{ id: 'best-practices', title: 'Best Practices', level: 2 }
];
const operations = [
{
name: 'The Endpoint object',
href: '/endpoint/endpoint-object',
method: 'OBJECT',
description: 'Complete structure and attributes of an Endpoint object.'
},
{
name: 'Create an endpoint',
href: '/endpoint/create-endpoint',
method: 'POST',
description: 'Create a new SIP endpoint for receiving and making calls.'
},
{
name: 'Delete an endpoint',
href: '/endpoint/delete-endpoint',
method: 'DELETE',
description: 'Permanently delete an existing endpoint.'
},
{
name: 'Retrieve an endpoint',
href: '/endpoint/retrieve-endpoint',
method: 'GET',
description: 'Get details of a specific endpoint including registration status.'
},
{
name: 'Update an endpoint',
href: '/endpoint/update-endpoint',
method: 'POST',
description: 'Update endpoint password, alias, or attached application.'
},
{
name: 'List all endpoints',
href: '/endpoint/list-all-endpoints',
method: 'GET',
description: 'Retrieve a list of all endpoints in your account.'
}
];
return (
# Endpoint
Manage SIP endpoints for making and receiving calls from IP phones, mobile devices, and SIP clients.
The Endpoint API allows you to create and manage SIP endpoints that can be used to make and receive calls through various devices and applications. Endpoints are essential for building communication systems with IP phones, softphones, and SIP clients.
**Note:** Each endpoint is assigned a unique SIP URI that external users can use to establish calls. Endpoints can be registered on SIP clients for real-time communication.
## What is an Endpoint?
A Vobiz endpoint, also known as a SIP endpoint, can be any device or application that uses the Session Initiation Protocol (SIP) to perform communications operations:
#### IP Phones   Hardware SIP phones that connect directly to your network.
#### Mobile Phones   Mobile apps using SIP softphone applications.
#### Desktop Applications   Web or desktop softphones using WebRTC or SIP clients.
#### Wireless Devices   Any wireless SIP-compatible device on your network.
**Use Cases:** Endpoints are commonly used for call center agents taking calls, business phone systems, customer support hotlines, and building custom VoIP applications.
## API Endpoint
Base URL
https://api.vobiz.ai/api/v1
Endpoint Base URI
https://api.vobiz.ai/api/v1/Account/{'{authID}'}/Endpoint/
Authentication Required:
- • **X-Auth-ID Header:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token Header:** Your account Auth Token
## Available Operations
{operations.map((operation) => (
{operation.method}
### {operation.name}
{operation.description}
View Documentation →
))}
## SIP Configuration
After creating an endpoint, configure your SIP client with the following details to connect:
#### Server Settings
SIP Server:
`sip.vobiz.ai`
Domain:
`sip.vobiz.ai`
Transport:
UDP/TCP/TLS
Port:
5060 (UDP/TCP), 5061 (TLS)
#### Credentials
Username:
`{'{endpoint_username}'}`
Password:
`{'{endpoint_password}'}`
Display Name:
`{'{alias}'}`
(optional)
Example Configuration:
{`SIP URI: sip:john_doe@sip.vobiz.ai Username: john_doe Password: SecurePassword123! Server: sip.vobiz.ai Port: 5060 Transport: UDP`}     **WebRTC Configuration:** For WebRTC applications, use JWT token authentication. Connect to `wss://sip.vobiz.ai:7443` and authenticate using a JWT token obtained from the API.
## Best Practices
#### Strong Passwords  Use complex passwords with minimum 8 characters, including mix of letters, numbers, and symbols.
#### Unique Usernames  Usernames must be unique within your account. Use descriptive names for easy identification.
#### Application Assignment  Assign applications to endpoints for automatic call routing and handling.
#### Permission Control  Only enable permissions (voice, video, messaging) that your endpoints actually need.
#### Monitor Registration  Check sip_registered field regularly to verify endpoint connectivity and troubleshoot issues.
#### Token Rotation  For WebRTC, use short-lived JWT tokens (1-4 hours) and rotate auth tokens periodically.
#### Sub-account Isolation  Use sub-accounts to isolate endpoints for different customers or departments.
#### Delete Unused Endpoints  Remove endpoints that are no longer in use to keep your account organized and secure.
);
}

---

# Page: /endpoint/endpoint-object

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# The Endpoint Object
Complete structure and attributes of an Endpoint object.
The Endpoint object represents a SIP endpoint in your account. Each endpoint has a unique identifier and can be registered on SIP clients to make and receive calls. The object structure varies slightly depending on whether the endpoint is currently registered on a SIP client.
**Registration Status:** When an endpoint is registered on a SIP client, additional fields like sip_contact, sip_expires, and sip_user_agent are included in the response.
## Attributes
## Examples
#### Unregistered Endpoint
Response when the endpoint is not currently registered on any SIP client:
```
{
"api_id": "550e8400-e29b-41d4-a716-446655440000",
"endpoint_id": "87654322",
"username": "jane_smith",
"alias": "Jane's Mobile",
"sip_uri": "sip:jane_smith@sip.vobiz.ai",
"sip_registered": "false",
"sip_contact": null,
"sip_expires": null,
"sip_user_agent": null,
"application": null,
"allow_voice": true,
"allow_message": true,
"allow_video": true,
"allow_same_domain": true,
"allow_other_domains": false,
"allow_phones": true,
"allow_apps": true,
"sub_account": null,
"resource_uri": "/v1/Account/{Auth_ID}/Endpoint/87654322/",
"created_at": "2025-10-26T14:20:00Z",
"updated_at": "2025-10-26T14:20:00Z"
}
```
#### Registered Endpoint
Response when the endpoint is actively registered on a SIP client:
```
{
"api_id": "550e8400-e29b-41d4-a716-446655440000",
"endpoint_id": "87654321",
"username": "john_doe",
"alias": "John's Desktop Phone",
"sip_uri": "sip:john_doe@sip.vobiz.ai",
"sip_registered": "true",
"sip_contact": "192.168.1.100:5060",
"sip_expires": "2025-10-28T11:30:00Z",
"sip_user_agent": "Zoiper v5.4.5",
"application": {
"app_id": "12345678",
"app_name": "Customer Service App",
"answer_url": "https://example.com/answer",
"answer_method": "POST"
},
"allow_voice": true,
"allow_message": true,
"allow_video": false,
"allow_same_domain": true,
"allow_other_domains": false,
"allow_phones": true,
"allow_apps": true,
"sub_account": null,
"resource_uri": "/v1/Account/{Auth_ID}/Endpoint/87654321/",
"created_at": "2025-10-27T10:30:00Z",
"updated_at": "2025-10-28T09:15:00Z"
}
```
**Note:** The password field is write-only and never returned in API responses for security purposes. Registration timestamps (sip_expires, created_at, updated_at) are in ISO 8601 format (UTC timezone).
);
}

---

# Page: /endpoint/create-endpoint

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Create an Endpoint
Create a new SIP endpoint for making and receiving calls.
This API allows you to create a new SIP endpoint that can be used to make and receive calls through IP phones, softphones, or SIP clients. Each endpoint is assigned a unique SIP URI and endpoint ID.
Authentication Required:
- • **X-Auth-ID Header:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
**SIP URI:** Your endpoint will be assigned a SIP URI in the format `sip:username@sip.vobiz.ai`
## HTTP Request
POST
https://api.vobiz.ai/api/v1/Account/{`{authID}`}/Endpoint/
## Request Parameters
## Response
If successful, returns "created" in the message field along with the endpoint_id, sip_uri, and resource_uri.
```
{
"api_id": "550e8400-e29b-41d4-a716-446655440000",
"message": "created",
"endpoint_id": "87654321",
"sip_uri": "sip:john_doe@sip.vobiz.ai",
"resource_uri": "/v1/Account/{Auth_ID}/Endpoint/87654321/"
}
```
```
{
"error": "invalid request parameters",
"details": {
"username": "This username already exists",
"password": "Password must be at least 8 characters"
}
}
```
## Examples
#### Basic Endpoint Creation
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Endpoint/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"username": "sales_desk",
"password": "VerySecurePass123!",
"alias": "Sales Team Desk Phone",
"allow_voice": true
}'
```
#### Create with Application and Permissions
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Endpoint/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"username": "john_doe",
"password": "SecurePassword123!",
"alias": "John'\''s Desktop Phone",
"application": 12345678,
"allow_voice": true,
"allow_message": true,
"allow_video": false,
"allow_same_domain": true,
"allow_other_domains": false,
"allow_phones": true,
"allow_apps": true
}'
```
**Best Practices:**
- • Use strong passwords (minimum 8 characters, mix of letters/numbers/symbols)
- • Use descriptive aliases to easily identify endpoints
- • Store the endpoint_id and sip_uri securely for future operations
- • Only enable permissions your endpoints actually need
- • Attach applications for automatic call routing
);
}

---

# Page: /endpoint/delete-endpoint

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Delete an Endpoint
Permanently delete an existing SIP endpoint from your account.
This API allows you to permanently delete an endpoint from your Vobiz account. Once deleted, the endpoint's SIP URI will no longer be accessible, and any devices or applications registered with this endpoint will be disconnected.
**Authentication Required:**
- • **X-Auth-ID Header:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token Header:** Your account Auth Token
**Warning - Permanent Deletion:**
This action is permanent and cannot be undone. Deleting an endpoint will immediately unregister it from all devices and make the SIP URI permanently unavailable. Ensure that no active calls or registrations depend on this endpoint before deletion.
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/Account/{`{authID}`}/Endpoint/{`{endpointID}`}/
**Base URL:**
`https://api.vobiz.ai/api/v1`
**Note:** No request parameters are required for this endpoint.
## Response
#### Success Response (204 No Content)
If successful, returns HTTP status code 204 No Content with an empty response body.
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Endpoint/87654321/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Before Deletion:**
- • Verify the endpoint is no longer needed
- • Check for any active registrations on SIP clients
- • Ensure no applications are routing calls to this endpoint
- • Consider updating endpoint instead if you need to change credentials
**Impact:** Deleting an endpoint will immediately unregister it from all devices and make the SIP URI permanently unavailable. This action cannot be reversed.
);
}

---

# Page: /endpoint/retrieve-endpoint

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Retrieve an Endpoint
Get detailed information about a specific endpoint including registration status.
This API allows you to retrieve the details of an existing endpoint. The response includes all endpoint attributes and, if the endpoint is currently registered on a SIP client, additional registration details.
**Authentication Required:**
- • **X-Auth-ID Header:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token Header:** Your account Auth Token
## HTTP Request
GET
https://api.vobiz.ai/api/v1/Account/{`{authID}`}/Endpoint/{`{endpointID}`}/
**Base URL:**
`https://api.vobiz.ai/api/v1`
**Note:** No request parameters are required for this endpoint.
## Response
Returns an Endpoint object if valid parameters were provided. Returns an error otherwise.
#### Success Response (200 OK)
```
{
"api_id": "550e8400-e29b-41d4-a716-446655440000",
"endpoint_id": "87654321",
"username": "john_doe",
"alias": "John's Desktop Phone",
"sip_uri": "sip:john_doe@sip.vobiz.ai",
"sip_registered": "true",
"sip_registration": {
"contact": "192.168.1.100:5060",
"expires": "2025-10-28T11:30:00Z",
"user_agent": "Zoiper v5.4.5",
"received": "203.0.113.42:5060",
"path": null
},
"application": {
"app_id": "12345678",
"app_name": "Customer Service App",
"answer_url": "https://example.com/answer",
"answer_method": "POST"
},
"allow_voice": true,
"allow_message": true,
"allow_video": false,
"allow_same_domain": true,
"allow_other_domains": false,
"allow_phones": true,
"allow_apps": true,
"sub_account": null,
"resource_uri": "/v1/Account/{Auth_ID}/Endpoint/87654321/",
"created_at": "2025-10-27T10:30:00Z",
"updated_at": "2025-10-28T09:15:00Z"
}
```
**Registration Details:** The sip_registration object contains detailed information about the endpoint's current SIP registration including contact address, expiration time, user agent, and received address. This object is only present when sip_registered is "true".
#### Error Response (404 Not Found)
```
{
"error": "Endpoint not found",
"endpoint_id": "99999999"
}
```
## Examples
#### cURL
```
curl -X GET https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Endpoint/87654321/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Use Cases:**
- • Verify endpoint registration status before making calls
- • Check which application is attached to an endpoint
- • Monitor SIP client registration expiration times
- • Retrieve SIP URI for sharing with external users
- • View detailed permission settings for an endpoint
);
}

---

# Page: /endpoint/update-endpoint

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Update an Endpoint
Update an endpoint's password, alias, or attached application.
This API allows you to update an existing endpoint's configuration. You can change the password for security purposes, update the alias for better identification, or modify the application that handles incoming calls to this endpoint.
**Authentication Required:**
- • **X-Auth-ID Header:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token Header:** Your account Auth Token
**Warning - Cannot Update:**
The following fields are locked after endpoint creation and cannot be updated: username, endpoint_id, domain, allow_same_domain, allow_other_domains, allow_phones, allow_apps. To change these values, you must create a new endpoint and delete the old one.
## HTTP Request
POST
https://api.vobiz.ai/api/v1/Account/{`{authID}`}/Endpoint/{`{endpointID}`}/
**Base URL:**
`https://api.vobiz.ai/api/v1`
## Request Parameters
**Note:** All parameters are optional. You only need to include the fields you want to update. Fields not provided will remain unchanged.
## Response
#### Success Response (202 Accepted)
If successful, returns HTTP status code 202 Accepted with no response body.
```
{
"error": "invalid request parameters",
"details": {
"password": "Password must be at least 8 characters"
}
}
```
#### Error Response (404 Not Found)
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Endpoint/87654321/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"alias": "John'\''s Updated Desktop Phone"
}'
```
#### Update Password
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Endpoint/87654321/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"password": "NewSecurePassword456!"
}'
```
#### Update Multiple Fields
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Endpoint/87654321/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"alias": "John'\''s Updated Desktop Phone",
"password": "NewSecurePassword456!",
"application": 98765432,
"allow_voice": true,
"allow_message": true,
"allow_video": true
}'
```
**Common Use Cases:**
- • Reset forgotten endpoint passwords
- • Update aliases to reflect role changes
- • Switch applications for different call routing logic
- • Rotate passwords regularly for security
- • Enable or disable video/messaging capabilities
**Tip:** After updating a password, SIP clients using this endpoint will need to re-register with the new credentials. Plan updates during maintenance windows to minimize disruption.
);
}

---

# Page: /endpoint/list-all-endpoints

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# List all Endpoints
Retrieve a paginated list of all SIP endpoints in your account.
This API allows you to retrieve a list of all endpoints configured in your account. The response includes complete details for each endpoint, including registration status and attached applications.
**Authentication Required:**
- • **X-Auth-ID Header:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Include your access token in the headers
## HTTP Request
GET
https://api.vobiz.ai/api/v1/Account/{`{authID}`}/Endpoint/
**Base URL:**
`https://api.vobiz.ai/api/v1`
#### Query Parameters
## Response
Returns a dictionary with an objects property that contains an array of Endpoint objects, along with a meta object containing pagination information.
```
{
"api_id": "550e8400-e29b-41d4-a716-446655440000",
"meta": {
"limit": 20,
"offset": 0,
"total_count": 45
},
"objects": [
{
"endpoint_id": "87654321",
"username": "john_doe",
"alias": "John's Desktop Phone",
"sip_uri": "sip:john_doe@sip.vobiz.ai",
"sip_registered": "true",
"sip_contact": "192.168.1.100:5060",
"sip_expires": "2025-10-28T11:30:00Z",
"sip_user_agent": "Zoiper v5.4.5",
"application": {
"app_id": "12345678",
"app_name": "Customer Service App"
},
"allow_voice": true,
"allow_message": true,
"allow_video": false,
"allow_same_domain": true,
"allow_other_domains": false,
"allow_phones": true,
"allow_apps": true,
"sub_account": null,
"resource_uri": "/v1/Account/{Auth_ID}/Endpoint/87654321/",
"created_at": "2025-10-27T10:30:00Z",
"updated_at": "2025-10-28T09:15:00Z"
},
{
"endpoint_id": "87654322",
"username": "jane_smith",
"alias": "Jane's Mobile",
"sip_uri": "sip:jane_smith@sip.vobiz.ai",
"sip_registered": "false",
"sip_contact": null,
"sip_expires": null,
"sip_user_agent": null,
"application": null,
"allow_voice": true,
"allow_message": true,
"allow_video": true,
"allow_same_domain": true,
"allow_other_domains": false,
"allow_phones": true,
"allow_apps": true,
"sub_account": null,
"resource_uri": "/v1/Account/{Auth_ID}/Endpoint/87654322/",
"created_at": "2025-10-26T14:20:00Z",
"updated_at": "2025-10-26T14:20:00Z"
}
]
}
```
**Note:** The response includes both registered and unregistered endpoints. Registered endpoints have sip_contact, sip_expires, and sip_user_agent populated, while unregistered endpoints have these fields set to null.
## Examples
#### cURL - List All Endpoints
```
curl -X GET "https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Endpoint/?limit=20&offset=0" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### cURL - Filter by Username
```
curl -X GET "https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Endpoint/?username__contains=john" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Build Endpoint Dashboard
```
async function getEndpointDashboard() {
const response = await fetch(
'https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Endpoint/',
{
headers: {
'X-Auth-ID': '{Auth_ID}',
'X-Auth-Token': '{access_token}'
}
}
);
const data = await response.json();
const dashboard = {
total: data.meta.total_count,
registered: data.objects.filter(ep => ep.sip_registered === 'true').length,
unregistered: data.objects.filter(ep => ep.sip_registered === 'false').length,
endpoints: data.objects.map(ep => ({
id: ep.endpoint_id,
alias: ep.alias,
username: ep.username,
registered: ep.sip_registered === 'true',
expires: ep.sip_expires || null
}))
};
return dashboard;
}
getEndpointDashboard().then(console.log);
```
**Use Cases:**
- • Build endpoint management dashboards
- • Monitor registration status across all endpoints
- • Audit endpoint configurations and attached applications
- • Identify unregistered endpoints for troubleshooting
- • Filter endpoints by username or alias for quick searches
);
}

---

# Page: /recording

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'api-endpoint', title: 'API Endpoint', level: 2 },
{ id: 'available-operations', title: 'Available Operations', level: 2 }
];
const operations = [
{
name: 'The Recording object',
href: '/recording/recording-object',
method: 'OBJECT',
description: 'Complete structure and attributes of a Recording object including storage and billing details.'
},
{
name: 'Retrieve a recording',
href: '/recording/retrieve-recording',
method: 'GET',
description: 'Get details of a specific recording based on its recording ID.'
},
{
name: 'List all recordings',
href: '/recording/list-all-recordings',
method: 'GET',
description: 'Retrieve a list of all recordings with extensive filtering options.'
},
{
name: 'Delete a recording',
href: '/recording/delete-recording',
method: 'DELETE',
description: 'Permanently delete a specific recording from your account.'
},
{
name: 'Export historical recordings',
href: '/recording/export-historical-recordings',
method: 'POST',
description: 'Export recordings as a downloadable archive sent via email (async operation).'
},
{
name: 'Bulk delete recordings',
href: '/recording/bulk-delete-recordings',
method: 'DELETE',
description: 'Delete multiple recordings matching filter criteria (async operation).'
}
];
return (
# Recording
Manage call and conference recordings in your account with retrieval and deletion capabilities.
The Recording API allows you to manage recordings that are stored in your Vobiz account. You can retrieve recording details including storage duration and billing information, list recordings with advanced filtering options, and delete recordings when they're no longer needed.
#### Call Recordings   Manage recordings from regular voice calls with detailed metadata.
#### Conference Recordings   Access recordings from conference calls and multiparty calls.
#### Storage Management   Track storage duration and associated monthly costs.
#### File Formats   Recordings are available in MP3 and WAV formats.
**Important:** Recordings are stored securely and accessible via HTTPS URLs. Storage costs are calculated monthly based on the recording duration and storage time.
## API Endpoint
Base URL
https://api.vobiz.ai/api/v1
Recording Base URI
https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Recording/
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Available Operations
{operations.map((operation) => (
{operation.method}
### {operation.name}
{operation.description}
View Documentation →
))}
**Note:** Vobiz automatically rounds recording durations to the nearest 60-second interval. Recordings shorter than 60 seconds are rounded up to 60 seconds for billing purposes.
);
}

---

# Page: /recording/recording-object

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 }
];
return (
# The Recording Object
Complete structure and attributes of a Vobiz Recording object.
The Recording object represents a call or conference recording stored in your Vobiz account. It includes detailed information about the recording file, associated call details, storage duration, and billing information.
**Note:** All recordings are automatically stored when call or conference recording is enabled. Storage costs are calculated based on duration and time stored, tracked in the `recording_storage_duration` and `monthly_recording_storage_amount` fields.
## Attributes
## Example
#### Complete Recording Object (Conference)
```
{
"api_id": "668470b7-7a8f-49b6-9011-50075754a50a",
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 1
},
"objects": [
{
"add_time": "2025-11-06 13:49:10.751756+00:00",
"call_uuid": "6e558798-499c-4a68-bc77-46f2c53d1f69",
"conference_name": "",
"from_number": "+918071387423",
"monthly_recording_storage_amount": 0,
"recording_duration_ms": "10080.00000",
"recording_end_ms": "1762436949502.00000",
"recording_format": "mp3",
"recording_id": "d7801b2e-e76d-4dd8-be9c-9e015a7267b8",
"recording_start_ms": "1762436939422.00000",
"recording_storage_duration": 1,
"recording_storage_rate": 0.005,
"recording_type": "call",
"recording_url": "https://media.vobiz.ai/api/v1/Account/MA_PU0XU668/Recording/d7801b2e-e76d-4dd8-be9c-9e015a7267b8.mp3",
"resource_uri": "/v1/Account/MA_PU0XU668/Recording/d7801b2e-e76d-4dd8-be9c-9e015a7267b8/",
"rounded_recording_duration": 60,
"to_number": "919624705678"
}
]
}
```
#### Regular Call Recording Example
```
{
"api_id": "668470b7-7a8f-49b6-9011-50075754a50a",
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 1
},
"objects": [
{
"add_time": "2025-11-06 13:49:10.751756+00:00",
"call_uuid": "6e558798-499c-4a68-bc77-46f2c53d1f69",
"conference_name": null,
"from_number": "+918071387423",
"monthly_recording_storage_amount": 0,
"recording_duration_ms": "10080.00000",
"recording_end_ms": "1762436949502.00000",
"recording_format": "mp3",
"recording_id": "d7801b2e-e76d-4dd8-be9c-9e015a7267b8",
"recording_start_ms": "1762436939422.00000",
"recording_storage_duration": 1,
"recording_storage_rate": 0.005,
"recording_type": "call",
"recording_url": "https://media.vobiz.ai/api/v1/Account/MA_PU0XU668/Recording/d7801b2e-e76d-4dd8-be9c-9e015a7267b8.mp3",
"resource_uri": "/v1/Account/MA_PU0XU668/Recording/d7801b2e-e76d-4dd8-be9c-9e015a7267b8/",
"rounded_recording_duration": 60,
"to_number": "919624705678"
}
]
}
```
**Key Differences:**
- • **Conference Recording:** `conference_name` contains the conference name, `recording_type` is "conference"
- • **Regular Call:** `conference_name` is null, `recording_type` is "call"
- • **Duration:** `recording_duration_ms` is actual duration, `rounded_recording_duration` is used for billing
- • **Storage Cost:** Calculated from `recording_storage_rate` × `recording_storage_duration`
**Important Notes:**
- • Recording URLs may be temporary - download recordings for permanent storage
- • `recording_storage_duration` increments daily and affects monthly costs
- • Timestamps (`recording_start_ms`, `recording_end_ms`) are in milliseconds since Unix epoch
- • Storage rate and amount are in USD
);
}

---

# Page: /recording/retrieve-recording

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Retrieve a Recording
Get detailed information about a specific recording using its recording ID.
This API allows you to retrieve the details of a specific recording based on its recording ID. The response includes complete information about the recording file, associated call details, storage duration, and billing information.
**Note:** You can obtain the recording_id from the List all recordings endpoint or from webhook notifications when recordings are created.
## HTTP Request
GET
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Recording/{`{recording_id}`}/
#### Authentication Headers
`X-Auth-ID:`
Your account auth_id (e.g., {'{Auth_ID}'})
`X-Auth-Token:`
Your account auth token
**Path Parameters:**
- • `{`{auth_id}`}` - Your account ID
- • `{`{recording_id}`}` - The unique recording identifier
## Response
Returns a complete Recording object with all attributes if the recording ID is valid.
#### Success Response (200 OK)
```
{
"api_id": "668470b7-7a8f-49b6-9011-50075754a50a",
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 1
},
"objects": [
{
"add_time": "2025-11-06 13:49:10.751756+00:00",
"call_uuid": "6e558798-499c-4a68-bc77-46f2c53d1f69",
"conference_name": "",
"from_number": "+918071387423",
"monthly_recording_storage_amount": 0,
"recording_duration_ms": "10080.00000",
"recording_end_ms": "1762436949502.00000",
"recording_format": "mp3",
"recording_id": "d7801b2e-e76d-4dd8-be9c-9e015a7267b8",
"recording_start_ms": "1762436939422.00000",
"recording_storage_duration": 1,
"recording_storage_rate": 0.005,
"recording_type": "call",
"recording_url": "https://media.vobiz.ai/api/v1/Account/MA_PU0XU668/Recording/d7801b2e-e76d-4dd8-be9c-9e015a7267b8.mp3",
"resource_uri": "/v1/Account/MA_PU0XU668/Recording/d7801b2e-e76d-4dd8-be9c-9e015a7267b8/",
"rounded_recording_duration": 60,
"to_number": "919624705678"
}
]
}
```
#### Error Response (404 Not Found)
```
{
"api_id": "correlation-id-uuid",
"error": "Recording not found"
}
```
## Examples
#### cURL Request
```
curl -X GET https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/abc123def456/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Download Recording File
Use the recording_url from the response to download the actual audio file:
```
# Step 1: Get the recording details
curl -X GET https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/abc123def456/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
# Step 2: Extract recording_url from response and download
# Example URL: https://media.vobiz.ai/api/v1/Account/MA_PU0XU668/Recording/d7801b2e-e76d-4dd8-be9c-9e015a7267b8.mp3
curl -o recording.mp3 "https://media.vobiz.ai/api/v1/Account/MA_PU0XU668/Recording/d7801b2e-e76d-4dd8-be9c-9e015a7267b8.mp3"
```
#### Using jq to Extract URL
```
# Get recording URL and download in one command
RECORDING_URL=$(curl -s -X GET https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/abc123def456/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
| jq -r '.recording_url')
curl -o recording.mp3 "$RECORDING_URL"
```
**Use Cases:**
- • Verify recording details before downloading
- • Check storage duration for billing purposes
- • Confirm recording format (MP3 vs WAV)
- • Get the download URL for archiving
- • Validate recording metadata (call_uuid, phone numbers)
**Tip:** The recording_url provides direct access to the audio file and can be used in media players or downloaded programmatically. However, these URLs may be temporary, so download recordings immediately for permanent storage.
**Important:** Always check the `api_id` field in responses for correlation and debugging purposes. This ID is useful when contacting support about specific requests.
);
}

---

# Page: /recording/list-all-recordings

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'query-parameters', title: 'Query Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# List All Recordings
Retrieve a paginated list of call recordings for your account.
This API endpoint allows you to fetch a list of call recordings with pagination support. You can filter recordings by type (trunk or extension) and control the number of results returned per request.
**Use Cases:** Retrieve recordings for archival, compliance, quality assurance, or to provide playback links to customers. The response includes recording IDs, call IDs for cross-referencing with CDRs, and download URLs.
## HTTP Request
GET
https://api.vobiz.ai/api/v1/Account/{`{ACCOUNT_ID}`}/Recording/
Case Sensitivity Notice:
Note that `Account` and `Recording` are capitalized in the URL path. Some APIs are case-sensitive, so ensure the capitalization matches exactly.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., MA_XXXXXXXX)
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Query Parameters
## Response
A successful request returns a `200 OK` status with a JSON array of recording objects.
```
{
"recordings": [
{
"recording_id": "REC_abc123def456",
"call_id": "7f8e9d2c-1a3b-4c5d-6e7f-8g9h0i1j2k3l",
"recording_type": "trunk",
"url": "https://recordings.vobiz.ai/files/REC_abc123def456.mp3",
"download_path": "/v1/Account/MA_XXXXXXXX/Recording/REC_abc123def456/download",
"duration": 312,
"created_at": "2026-01-23T10:30:00Z",
"file_size": 2457600,
"format": "mp3"
},
{
"recording_id": "REC_xyz789uvw012",
"call_id": "2a3b4c5d-6e7f-8g9h-0i1j-2k3l4m5n6o7p",
"recording_type": "trunk",
"url": "https://recordings.vobiz.ai/files/REC_xyz789uvw012.mp3",
"download_path": "/v1/Account/MA_XXXXXXXX/Recording/REC_xyz789uvw012/download",
"duration": 125,
"created_at": "2026-01-23T09:15:00Z",
"file_size": 987600,
"format": "mp3"
}
],
"pagination": {
"limit": 20,
"offset": 0,
"total": 150,
"has_more": true
}
}
```
#### Response Fields
- • `recording_id` - Unique identifier for the recording (used for download)
- • `call_id` - Cross-reference with CDR records
- • `url` or `download_path` - Link to the actual audio file (MP3/WAV)
- • `created_at` - Timestamp when the recording was made
- • `duration` - Recording length in seconds
- • `recording_type` - Type of recording (trunk/extension)
## Examples
#### cURL - List Trunk Recordings
```
curl -X GET "https://api.vobiz.ai/api/v1/Account/{ACCOUNT_ID}/Recording/?limit=20&offset=0&recording_type=trunk" \\
-H "X-Auth-ID: {ACCOUNT_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}" \\
-H "Content-Type: application/json"
```
#### Generic Template (Use Your Own Values)
```
curl -X GET "https://api.vobiz.ai/api/v1/Account/{ACCOUNT_ID}/Recording/?limit={LIMIT}&offset={OFFSET}&recording_type={TYPE}" \\
-H "X-Auth-ID: {ACCOUNT_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}" \\
-H "Content-Type: application/json"
```
#### Parameter Quick Reference
Parameter
Example
Description
`limit`
20
Number of records to return
`offset`
0
Starting position (0 for first page, 20 for second, etc.)
`recording_type`
trunk
Filter by type: "trunk" or "extension"
**Quick Tips:**
- • **Pagination:** Use `offset` to navigate through pages (offset = page × limit)
- • **Recording Type:** Filter by "trunk" or "extension" to get specific recording types
- • **Case Sensitive:** Ensure "Account" and "Recording" are capitalized in the URL
- • **Cross-Reference:** Use `call_id` to match recordings with CDR entries
**Next Steps:**
- • Use the `recording_id` to download specific recordings
- • Cross-reference with CDR data using `call_id` for complete call information
- • Store recording URLs for playback or archival purposes
- • Implement pagination to retrieve all recordings efficiently
);
}

---

# Page: /recording/delete-recording

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Delete a Recording
Permanently delete a specific recording from your account.
This API allows you to permanently delete a recording from your Vobiz account using the recording ID. Once deleted, the recording file will be permanently removed and cannot be recovered.
⚠️ Warning: This action is permanent and cannot be undone!
- • The recording file will be completely removed from storage
- • The recording URL will no longer be accessible
- • All metadata associated with this recording will be deleted
- • This operation cannot be reversed
**Best Practice:** Before deleting, consider retrieving the recording details and downloading the audio file if you might need it for compliance or archival purposes.
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Recording/{`{recording_id}`}/
#### Authentication Headers
`X-Auth-ID:`
Your account auth_id (e.g., {'{Auth_ID}'})
`X-Auth-Token:`
Your account auth token
**Path Parameters:**
- • `{`{auth_id}`}` - Your account ID
- • `{`{recording_id}`}` - The unique recording identifier to delete
## Response
#### Success Response (204 No Content)
If the recording was successfully deleted, the API returns HTTP 204 with no response body.
```
{
"api_id": "correlation-id-uuid",
"error": "Recording not found"
}
```
## Examples
#### Basic Delete Request
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/abc123def456/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Safe Delete Workflow: Verify Before Deleting
Best practice: Retrieve recording details before deletion to confirm you're deleting the correct file:
```
# Step 1: Get recording details to verify
curl -X GET https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/abc123def456/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
# Step 2: Review the output, confirm it's the right recording
# Check: call_uuid, conference_name, from_number, to_number, add_time
# Step 3: Delete if confirmed
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/abc123def456/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Archive Then Delete Workflow
Download the recording before deleting for backup purposes:
```
#!/bin/bash
RECORDING_ID="abc123def456"
ACCOUNT_ID="{Auth_ID}"
AUTH_ID="YOUR_AUTH_ID"
AUTH_TOKEN="YOUR_AUTH_TOKEN"
# Get recording details
RESPONSE=$(curl -s -X GET https://api.vobiz.ai/api/v1/Account/\${ACCOUNT_ID}/Recording/\${RECORDING_ID}/ \\
-H "X-Auth-ID: \${AUTH_ID}" \\
-H "X-Auth-Token: \${AUTH_TOKEN}")
# Extract recording URL
RECORDING_URL=$(echo \${RESPONSE} | jq -r '.recording_url')
# Download the recording file
echo "Downloading recording..."
curl -o "\${RECORDING_ID}.mp3" "\${RECORDING_URL}"
# Verify download was successful
if [ -f "\${RECORDING_ID}.mp3" ]; then
echo "Download successful. File size: $(ls -lh \${RECORDING_ID}.mp3 | awk '{print \$5}')"
# Delete from Vobiz
echo "Deleting recording from Vobiz..."
curl -X DELETE https://api.vobiz.ai/api/v1/Account/\${ACCOUNT_ID}/Recording/\${RECORDING_ID}/ \\
-H "X-Auth-ID: \${AUTH_ID}" \\
-H "X-Auth-Token: \${AUTH_TOKEN}"
echo "Recording deleted successfully"
else
echo "Download failed. Recording NOT deleted."
fi
```
#### Check Deletion Status
Verify the recording was deleted by attempting to retrieve it:
```
# This should return 404 if deletion was successful
curl -X GET https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/abc123def456/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Before Deleting - Checklist:**
- ✓ Download the recording file if you need to archive it
- ✓ Verify you have the correct recording_id
- ✓ Check for any compliance or legal requirements for retention
- ✓ Confirm this isn't an active/recent recording that might be needed
- ✓ Consider storage costs vs. retention needs
**Common Use Cases:**
- • Remove old recordings to reduce storage costs
- • Delete recordings after archiving to external storage
- • Clean up test recordings from development
- • Comply with data retention policies (e.g., GDPR right to deletion)
- • Remove recordings that failed quality checks
**Tip:** For deleting multiple recordings, use the [Bulk Delete Recordings](/recording/bulk-delete-recordings) endpoint instead of making individual delete requests. This is more efficient and reduces API calls.
**Note:** HTTP 204 response means success. If you receive a 404 error and you're certain the recording ID is correct, the recording may have already been deleted by another process or user.
);
}

---

# Page: /recording/export-historical-recordings

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-body', title: 'Request Body', level: 2 },
{ id: 'constraints', title: 'Constraints', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Export Historical Recordings
Export recordings as a downloadable archive sent via email (async operation).
This API allows you to export recordings matching your filter criteria. Recordings are packaged as a downloadable archive and sent via email. This is an asynchronous operation that processes in the background.
🔄 Async Operation Workflow:
- Request is validated and queued as async task
- System processes recordings matching your filters
- Recordings are packaged as downloadable archive
- Download link is emailed to all recipient addresses
- Archive typically available within 15-60 minutes depending on volume
**Important:** Only one export request can run at a time per account. If an export is already in progress, you must wait for it to complete before starting a new one.
## HTTP Request
POST
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/export/recording/
#### Authentication Headers
`X-Auth-ID:`
Your account auth_id (e.g., {'{Auth_ID}'})
`X-Auth-Token:`
Your account auth token
`Content-Type:`
application/json
## Request Body
#### Date Range Filters (Option 1)
#### Storage Duration Filters (Option 2 - Alternative to Date Range)
#### Additional Filters (Only for ranges ≤ 30 days)
**Note:** Additional filters (from_number, to_number, etc.) only work when your date range or storage duration range is 30 days or less.
## Constraints & Validation
❌ Cannot combine from/to with storage duration filters
❌ Cannot use __gt and __gte together (choose one)
❌ Cannot use __lt and __lte together (choose one)
⚠️ Maximum date range: 1 year (366 days)
⚠️ Maximum storage duration range: 30 days
⚠️ Filters only apply for ranges ≤ 30 days
⚠️ When using range filters (__gte/__lte), both must be provided
🔒 Only one export can run at a time per account
## Response
#### Success Response (202 Accepted)
The export request has been queued and will be processed in the background:
```
{
"api_id": "correlation-id-uuid",
"status": "success"
}
```
#### Error Response (403 Forbidden)
Another export is already in progress:
```
{
"status": "failure",
"message": "An Export Historic Recording request is already in process. Please try again in sometime."
}
```
#### Error Response (400 Bad Request)
Invalid request parameters:
```
{
"status": "failure",
"message": "From/To cannot be used with recording storage duration"
}
```
## Examples
#### Export Last 7 Days (Date Range)
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/export/recording/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"from": "2025-01-23 00:00:00",
"to": "2025-01-30 23:59:59",
"recipient": {
"customer_account": ["admin@example.com"]
}
}'
```
#### Export Using Storage Duration
Export recordings exactly 7 days old:
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/export/recording/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"recording_storage_duration": "7",
"recipient": {
"customer_account": ["admin@example.com"]
}
}'
```
#### Export with Storage Duration Range
Export recordings between 7 and 30 days old:
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/export/recording/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"recording_storage_duration__gte": "7",
"recording_storage_duration__lte": "30",
"recipient": {
"customer_account": ["admin@example.com"]
}
}'
```
#### Export with Filters (Conference Recordings)
Export conference recordings in MP3 format from last 30 days:
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/export/recording/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"from": "2025-01-01 00:00:00",
"to": "2025-01-30 23:59:59",
"conference_name": "TeamMeeting",
"recording_format": "mp3",
"recipient": {
"customer_account": ["admin@example.com", "backup@example.com"]
}
}'
```
#### Export with Phone Number Filter
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/export/recording/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"from": "2025-01-15 00:00:00",
"to": "2025-01-30 23:59:59",
"from_number": "+14155551234",
"recipient": {
"customer_account": ["admin@example.com"]
}
}'
```
**Use Cases:**
- • Backup recordings to external storage before deletion
- • Archive old recordings for compliance
- • Export specific conference recordings for review
- • Download recordings for specific phone numbers
- • Create monthly recording backups
**Tip:** For large date ranges ({'>'}30 days), don&apos;t use additional filters. Export in smaller batches if you need filtered results.
**Email Delivery:**
- • Check spam/junk folders if not received within 1 hour
- • Verify email addresses are valid before requesting
- • Use multiple recipients for redundancy
- • Wait for completion email before starting another export
);
}

---

# Page: /recording/bulk-delete-recordings

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'query-parameters', title: 'Query Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Bulk Delete Recordings
Delete multiple recordings matching filter criteria (async operation).
This API allows you to delete multiple recordings at once based on filter criteria. This is an asynchronous operation that processes deletions in the background, making it efficient for removing large numbers of recordings.
⚠️ WARNING: This action is permanent and cannot be undone!
- • All recordings matching your filters will be permanently deleted
- • Recording files will be completely removed from storage
- • Recording URLs will no longer be accessible
- • All metadata associated with these recordings will be deleted
- • This operation cannot be reversed
🔄 Async Operation:
- Request is validated and queued as async task
- System identifies all recordings matching your filters
- Recordings are deleted in batches
- Operation typically completes within minutes to hours depending on volume
**Best Practice:** Before bulk deleting, use the [List Recordings](/recording/list-all-recordings) endpoint with the same filters to verify which recordings will be deleted. Check the `meta.total_count` to see how many recordings match.
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/Account/{`{auth_id}`}/Recording/BulkDelete/
#### Authentication Headers
`X-Auth-ID:`
Your account auth_id (e.g., {'{Auth_ID}'})
`X-Auth-Token:`
Your account auth token
## Query Parameters
Use query parameters to filter which recordings to delete. At least one filter parameter is recommended to avoid accidentally deleting all recordings.
Date Format Requirements:
- • Format: `YYYY-MM-DD HH:MM:SS`
- • Example: `2025-01-15 10:30:45`
- • Use 24-hour time format
- • Include seconds (even if 00)
- • URL encode spaces as %20
## Response
#### Success Response (202 Accepted)
The bulk delete request has been queued and will be processed in the background:
```
{
"api_id": "correlation-id-uuid",
"status": "successfully queued bulk delete request"
}
```
**Note:** A 202 response means the request has been accepted and queued. The actual deletion happens asynchronously in the background. Verify completion by checking if recordings still exist using the List Recordings endpoint.
## Examples
#### Delete Recordings from January 2025
```
curl -X DELETE "https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/BulkDelete/?add_time__gte=2025-01-01%2000:00:00&add_time__lte=2025-01-31%2023:59:59" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Delete All Recordings for a Specific Conference
```
curl -X DELETE "https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/BulkDelete/?conference_name=TeamMeeting" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Delete Recordings from Specific Phone Number
```
curl -X DELETE "https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/BulkDelete/?from_number=%2B14155551234" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
Note: URL encode the + symbol as %2B
#### Delete WAV Format Recordings
```
curl -X DELETE "https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/BulkDelete/?recording_format=wav" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Safe Workflow: Verify Before Deleting
Always check what will be deleted before running the bulk delete:
```
# Step 1: List recordings that match your filters
curl -X GET "https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/?add_time__gte=2025-01-01%2000:00:00&add_time__lte=2025-01-31%2023:59:59" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
# Check the meta.total_count to see how many will be deleted
# Step 2: Review the output and confirm
# Step 3: Run bulk delete with same filters
curl -X DELETE "https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/BulkDelete/?add_time__gte=2025-01-01%2000:00:00&add_time__lte=2025-01-31%2023:59:59" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Combine Multiple Filters
Delete conference recordings in MP3 format from a specific date range:
```
curl -X DELETE "https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Recording/BulkDelete/?conference_name=DailyStandup&recording_format=mp3&add_time__gte=2025-01-01%2000:00:00&add_time__lte=2025-01-15%2023:59:59" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Before Bulk Deleting - Checklist:**
- ✓ Use List Recordings endpoint first to verify count
- ✓ Export/download recordings if you need backups
- ✓ Double-check your filter parameters
- ✓ Verify legal/compliance retention requirements
- ✓ Confirm this is intentional (deletions are permanent)
- ✓ Test with a small date range first if unsure
**Common Use Cases:**
- • Clean up old recordings to reduce storage costs
- • Delete test recordings from development/staging
- • Remove recordings after exporting to external storage
- • Comply with data retention policies (e.g., delete after 90 days)
- • Remove recordings for specific conferences that ended
**Tip:** For automated cleanup policies, combine bulk delete with storage duration filters. For example, delete all recordings older than 90 days on a monthly schedule.
**Verify Deletion:**
After bulk delete completes, run the List Recordings endpoint with the same filters. If `meta.total_count` is 0, all matching recordings were successfully deleted.
);
}

---

# Page: /audio-stream

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'key-features', title: 'Key Features', level: 2 },
{ id: 'use-cases', title: 'Use Cases', level: 2 },
{ id: 'api-endpoint', title: 'API Endpoint', level: 2 },
{ id: 'quick-start', title: 'Quick Start', level: 2 }
];
return (
{/* Header */}
# Audio Stream
Vobiz's audio streaming resource lets you receive raw audio input over WebSocket (wss or ws) URLs from live phone calls in near real time.
{/* Introduction */}
The Audio Stream API enables real-time bidirectional audio streaming over WebSocket connections during active phone calls. Stream audio from calls to your application, process it in real-time, and optionally send audio back to the caller.
**Base Endpoint:** `https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Call/{'{call_uuid}'}/Stream/`
{/* Key Features */}
## Key Features
### Bidirectional Streaming
Stream audio from the call to your WebSocket and send audio back to the caller in real-time.
### Multiple Audio Tracks
Choose to stream inbound audio only, outbound audio only, or both tracks simultaneously.
### Flexible Codecs
Support for L16 (8kHz/16kHz) and μ-law (8kHz) audio formats to match your application needs.
### Status Callbacks
Receive HTTP callbacks when streams start, stop, or reach checkpoints for monitoring and logging.
{/* Use Cases */}
## Use Cases
### Real-Time Transcription
Stream call audio to speech-to-text services like Google Speech, AWS Transcribe, or Deepgram for live transcription and conversation analysis.
### AI Voice Agents
Power conversational AI agents that can listen to callers and respond with generated speech in real-time using services like ElevenLabs, OpenAI, or custom AI models.
### Sentiment Analysis
Analyze caller emotions and sentiment during live calls to provide insights for customer service teams or trigger automated workflows.
### Call Recording & Processing
Capture and process audio streams for compliance, quality assurance, training, or analytics purposes.
{/* API Endpoint */}
## API Endpoint
POST
https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Call/{'{call_uuid}'}/Stream/
**Authentication Required:** All requests must include X-Auth-ID and X-Auth-Token headers.
```
curl -X POST https://api.vobiz.ai/api/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy/Stream/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"service_url": "wss://yourapp.example.com/audiostream",
"bidirectional": true,
"audio_track": "both",
"content_type": "audio/x-l16;rate=16000"
}'
```
**Next Steps:**
- • Review the [Audio Stream Object](/audio-stream/audio-stream-object) to understand all available attributes
- • Learn how to [initiate an audio stream](/audio-stream/initiate-audio-stream) on an active call
- • Explore [retrieving stream details](/audio-stream/retrieve-audio-stream) and managing streams
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /audio-stream/audio-stream-object

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 }
];
return (
{/* Header */}
# The Audio Stream Object
The Audio Stream object lets you receive the raw audio of a live phone call over a configured WebSocket in near real time.
{/* Introduction */}
An Audio Stream object is created when you initiate audio streaming on an active call. The stream connects to your WebSocket URL and transmits raw audio data in real-time. You can configure various parameters like audio track direction, codec, sample rate, and bidirectional capabilities.
**Note:** Each stream has a unique `stream_id` that can be used to retrieve stream details or stop the stream.
{/* Attributes */}
## Attributes
{/* Example */}
## Example Audio Stream Object
```
{
"api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
"audio_track": "both",
"bidirectional": false,
"bill_duration": 27,
"billed_amount": "0.00300",
"call_uuid": "call-uuid-xxxx-yyyy-zzzz-abcd",
"created_at": "2025-11-14 13:23:44.136962+00:00",
"end_time": "2025-11-14 18:53:43+05:30",
"account_id": "MA_AABBCC",
"resource_uri": "/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy-zzzz-abcd/Stream/stream-id-aabbcc-ddeeff/",
"rounded_bill_duration": 60,
"service_url": "wss://yourapp.example.com/audiostream",
"start_time": "2025-11-14 18:53:16+05:30",
"stream_id": "stream-id-aabbcc-ddeeff"
}
```
### Important Notes
- When `bidirectional` is true, `audio_track` should not be "outbound" or "both"
- The `stream_id` is required for retrieve and stop operations
- Billing is calculated based on stream duration and pricing tier
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /audio-stream/initiate-audio-stream

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
{/* Header */}
# Initiate an Audio Stream
This method lets you initiate an audio stream for an active call and send that stream to a secure WebSocket URL.
{/* Introduction */}
Initiate real-time audio streaming for an active call. The audio stream connects to your WebSocket URL and transmits raw audio data that you can process, transcribe, or analyze in real-time.
**Requirement:** The call must be active (in-progress status) before you can initiate an audio stream. You'll need the `call_uuid` from when the call was created.
{/* HTTP Request */}
## HTTP Request
POST
https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Call/{'{call_uuid}'}/Stream/
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
{/* Request Parameters */}
## Request Parameters
**Important:** When `bidirectional` is set to true, the `audio_track` value should not be set to "outbound" or "both".
{/* Response */}
## Response
Returns the complete audio stream object including the auto-generated `stream_id` UUID and timestamps.
```
{
"api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
"audio_track": "both",
"bidirectional": false,
"bill_duration": 27,
"billed_amount": "0.00300",
"call_uuid": "call-uuid-xxxx-yyyy-zzzz-abcd",
"created_at": "2025-11-14 02:44:50.617032+00:00",
"end_time": "2025-11-14 08:14:50+05:30",
"account_id": "MA_AABBCC",
"resource_uri": "/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy-zzzz-abcd/Stream/stream-id-aabbcc-ddeeff/",
"rounded_bill_duration": 60,
"service_url": "wss://yourapp.example.com/audiostream",
"start_time": "2025-11-14 08:14:29+05:30",
"stream_id": "stream-id-aabbcc-ddeeff"
}
```
{/* Examples */}
## Examples
{/* Basic Stream */}
#### cURL - Basic Audio Stream
```
curl -X POST https://api.vobiz.ai/api/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy/Stream/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"service_url": "wss://yourapp.example.com/audiostream"
}'
```
{/* Bidirectional Stream */}
#### cURL - Bidirectional Stream with Callbacks
```
curl -X POST https://api.vobiz.ai/api/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy/Stream/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"service_url": "wss://yourapp.example.com/audiostream",
"bidirectional": true,
"audio_track": "inbound",
"content_type": "audio/x-l16;rate=16000",
"status_url": "https://yourapp.example.com/stream-status",
"status_method": "POST"
}'
```
{/* Advanced Stream */}
#### cURL - Advanced Stream with Extra Headers
```
curl -X POST https://api.vobiz.ai/api/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy/Stream/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"service_url": "wss://yourapp.example.com/audiostream",
"bidirectional": false,
"audio_track": "both",
"stream_timeout": 3600,
"content_type": "audio/x-l16;rate=16000",
"extra_headers": "sessionid=abc123,userid=xyz789",
"status_url": "https://yourapp.example.com/stream-status"
}'
```
**Next Steps:**
- • Save the `stream_id` for retrieval and management
- • Configure your WebSocket server to handle incoming audio data
- • Set up status callback handlers to monitor stream lifecycle events
- • Test the stream with a sample call before production use
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /audio-stream/retrieve-audio-stream

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
{/* Header */}
# Retrieve an Audio Stream
This method lets you retrieve the details of an audio stream.
{/* Introduction */}
Use this endpoint to retrieve information about a specific audio stream, including its configuration, status, duration, and billing details. You'll need the `stream_id` (also called `stream_uuid`) that was returned when the stream was initiated.
**Use Case:** Retrieve stream details to monitor stream status, verify configuration, check billing information, or audit stream usage.
{/* HTTP Request */}
## HTTP Request
GET
https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Call/{'{call_uuid}'}/Stream/{'{stream_uuid}'}/
**Authentication:** Include `X-Auth-ID` and `X-Auth-Token` headers.
{/* Arguments */}
## Arguments
No arguments need to be passed. The `stream_uuid` is specified in the URL path.
{/* Response */}
## Response
Returns the complete audio stream object with all configuration details, timestamps, and billing information.
```
{
"api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
"audio_track": "both",
"bidirectional": false,
"bill_duration": 27,
"billed_amount": "0.00300",
"call_uuid": "call-uuid-xxxx-yyyy-zzzz-abcd",
"created_at": "2025-11-14 13:23:44.136962+00:00",
"end_time": "2025-11-14 18:53:43+05:30",
"account_id": "MA_AABBCC",
"resource_uri": "/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy-zzzz-abcd/Stream/stream-id-aabbcc-ddeeff/",
"rounded_bill_duration": 60,
"service_url": "wss://yourapp.example.com/audiostream",
"start_time": "2025-11-14 18:53:16+05:30",
"stream_id": "stream-id-aabbcc-ddeeff"
}
```
{/* Examples */}
## Examples
#### cURL - Retrieve Stream
```
curl -X GET https://api.vobiz.ai/api/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy/Stream/stream-id-aabbcc-ddeeff/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Node.js Example
```
const axios = require('axios');
const authId = 'MA_AABBCC';
const callUuid = 'call-uuid-xxxx-yyyy';
const streamId = 'stream-id-aabbcc-ddeeff';
axios.get(\`https://api.vobiz.ai/api/v1/Account/\${authId}/Call/\${callUuid}/Stream/\${streamId}/\`, {
headers: {
'X-Auth-ID': 'YOUR_AUTH_ID',
'X-Auth-Token': 'YOUR_AUTH_TOKEN'
}
})
.then(response => {
console.log('Stream details:', response.data);
console.log('Stream status:', response.data.end_time ? 'Ended' : 'Active');
console.log('Duration:', response.data.bill_duration, 'seconds');
})
.catch(error => {
console.error('Error retrieving stream:', error.response.data);
});
```
#### Python Example
```
import requests
auth_id = 'MA_AABBCC'
call_uuid = 'call-uuid-xxxx-yyyy'
stream_id = 'stream-id-aabbcc-ddeeff'
url = f'https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/{stream_id}/'
headers = {
'X-Auth-ID': 'YOUR_AUTH_ID',
'X-Auth-Token': 'YOUR_AUTH_TOKEN'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
stream_data = response.json()
print(f"Stream ID: {stream_data['stream_id']}")
print(f"Service URL: {stream_data['service_url']}")
print(f"Duration: {stream_data['bill_duration']} seconds")
print(f"Cost: {stream_data['billed_amount']}")
else:
print(f"Error: {response.status_code}")
```
**Tip:** Use this endpoint to:
- • Monitor stream status and verify it's active
- • Check billing duration and cost
- • Verify stream configuration (codec, audio track, etc.)
- • Audit stream usage across your account
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /audio-stream/retrieve-all-audio-streams

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
{/* Header */}
# Retrieve All Audio Streams
This method lets you retrieve all active and inactive audio streams for a given call UUID.
{/* Introduction */}
Retrieve details of all audio streams (both active and inactive) for a specific call. This endpoint returns stream configuration, status, duration, and billing information.
**Note:** The response returns a single stream object with all stream details for the call.
{/* HTTP Request */}
## HTTP Request
GET
https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Call/{'{call_uuid}'}/Stream/
**Authentication:** Include `X-Auth-ID` and `X-Auth-Token` headers.
{/* Arguments */}
## Arguments
No arguments need to be passed. All streams for the specified call will be returned.
{/* Response */}
## Response
Returns the audio stream object with complete configuration details, timestamps, and billing information.
```
{
"api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
"audio_track": "both",
"bidirectional": false,
"bill_duration": 21,
"billed_amount": "0.00300",
"call_uuid": "call-uuid-xxxx-yyyy-zzzz-abcd",
"created_at": "2025-11-14 02:44:50.617032+00:00",
"end_time": "2025-11-14 08:14:50+05:30",
"account_id": "MA_AABBCC",
"resource_uri": "/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy-zzzz-abcd/Stream/stream-id-aabbcc-ddeeff/",
"rounded_bill_duration": 60,
"service_url": "ws://yourapp.example.com/audiostream",
"start_time": "2025-11-14 08:14:29+05:30",
"stream_id": "stream-id-aabbcc-ddeeff"
}
```
{/* Examples */}
## Examples
#### cURL - Retrieve All Streams
```
curl -X GET https://api.vobiz.ai/api/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy/Stream/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Node.js Example
```
const axios = require('axios');
const authId = 'MA_AABBCC';
const callUuid = 'call-uuid-xxxx-yyyy';
axios.get(\`https://api.vobiz.ai/api/v1/Account/\${authId}/Call/\${callUuid}/Stream/\`, {
headers: {
'X-Auth-ID': 'YOUR_AUTH_ID',
'X-Auth-Token': 'YOUR_AUTH_TOKEN'
}
})
.then(response => {
const stream = response.data;
console.log('Stream details:', stream);
console.log(\`Stream ID: \${stream.stream_id}\`);
console.log(\`Audio Track: \${stream.audio_track}\`);
console.log(\`Duration: \${stream.bill_duration} seconds\`);
console.log(\`Cost: \${stream.billed_amount}\`);
console.log(\`Status: \${stream.end_time ? 'Ended' : 'Active'}\`);
})
.catch(error => {
console.error('Error retrieving streams:', error.response.data);
});
```
#### Python Example
```
import requests
auth_id = 'MA_AABBCC'
call_uuid = 'call-uuid-xxxx-yyyy'
url = f'https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/'
headers = {
'X-Auth-ID': 'YOUR_AUTH_ID',
'X-Auth-Token': 'YOUR_AUTH_TOKEN'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
stream = response.json()
print(f"Stream ID: {stream['stream_id']}")
print(f"Service URL: {stream['service_url']}")
print(f"Audio Track: {stream['audio_track']}")
print(f"Duration: {stream['bill_duration']} seconds")
print(f"Cost: {stream['billed_amount']}")
status = 'Ended' if stream.get('end_time') else 'Active'
print(f"Status: {status}")
else:
print(f"Error: {response.status_code}")
```
**Use Cases:**
- • Monitor stream status for a specific call
- • Verify stream configuration and settings
- • Check billing duration and costs
- • Audit stream usage across your account
- • Track whether a stream is active or has ended
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /audio-stream/stop-audio-stream

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'stop-specific-stream', title: 'Stop a Specific Stream', level: 2 },
{ id: 'stop-all-streams', title: 'Stop All Streams', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
{/* Header */}
# Stop an Audio Stream
This method lets you stop an active audio stream on a call.
{/* Introduction */}
Stopping an audio stream terminates the WebSocket connection and stops transmitting audio data. You can either stop a specific stream by providing its `stream_id`, or stop all active streams for a call.
**Note:** Stopping a stream does not affect the call itself. The call will continue and subsequent XML elements (if any) will execute. If you configured a `status_url`, a StopStream event will be sent.
{/* HTTP Request - Specific Stream */}
## Stop a Specific Stream
DELETE
https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Call/{'{call_uuid}'}/Stream/{'{stream_uuid}'}/
**Authentication:** Include `X-Auth-ID` and `X-Auth-Token` headers.
**Success Response (200 OK):**
```
{
"message": "Stream stopped successfully",
"stream_id": "stream-id-aabbcc-ddeeff"
}
```
**Error Response (404 Not Found):**
```
{
"api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
"error": "No active stream found"
}
```
{/* HTTP Request - All Streams */}
## Stop All Streams
DELETE
https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/Call/{'{call_uuid}'}/Stream/
Omit the `stream_uuid` from the path to stop all active streams for the call.
**Success Response (200 OK):**
```
{
"message": "All streams stopped successfully",
"streams_stopped": 2
}
```
**Error Response (404 Not Found):**
```
{
"api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
"error": "No active stream found"
}
```
{/* Examples */}
## Examples
{/* Stop Specific Stream */}
### Stop a Specific Stream
#### cURL
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy/Stream/stream-id-aabbcc-ddeeff/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Node.js
```
const axios = require('axios');
const authId = 'MA_AABBCC';
const callUuid = 'call-uuid-xxxx-yyyy';
const streamId = 'stream-id-aabbcc-ddeeff';
axios.delete(\`https://api.vobiz.ai/api/v1/Account/\${authId}/Call/\${callUuid}/Stream/\${streamId}/\`, {
headers: {
'X-Auth-ID': 'YOUR_AUTH_ID',
'X-Auth-Token': 'YOUR_AUTH_TOKEN'
}
})
.then(response => {
console.log('Stream stopped:', response.data);
})
.catch(error => {
if (error.response && error.response.status === 404) {
console.log('No active stream found');
} else {
console.error('Error stopping stream:', error.response.data);
}
});
```
#### Python
```
import requests
auth_id = 'MA_AABBCC'
call_uuid = 'call-uuid-xxxx-yyyy'
stream_id = 'stream-id-aabbcc-ddeeff'
url = f'https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/{stream_id}/'
headers = {
'X-Auth-ID': 'YOUR_AUTH_ID',
'X-Auth-Token': 'YOUR_AUTH_TOKEN'
}
response = requests.delete(url, headers=headers)
if response.status_code == 200:
print("Stream stopped successfully")
print(response.json())
elif response.status_code == 404:
print("No active stream found")
else:
print(f"Error: {response.status_code}")
```
{/* Stop All Streams */}
### Stop All Streams
#### cURL
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy/Stream/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### Node.js
```
const axios = require('axios');
const authId = 'MA_AABBCC';
const callUuid = 'call-uuid-xxxx-yyyy';
axios.delete(\`https://api.vobiz.ai/api/v1/Account/\${authId}/Call/\${callUuid}/Stream/\`, {
headers: {
'X-Auth-ID': 'YOUR_AUTH_ID',
'X-Auth-Token': 'YOUR_AUTH_TOKEN'
}
})
.then(response => {
console.log('All streams stopped:', response.data);
console.log(\`Stopped \${response.data.streams_stopped} streams\`);
})
.catch(error => {
console.error('Error stopping streams:', error.response.data);
});
```
**Best Practices:**
- • Stop streams when they're no longer needed to avoid unnecessary costs
- • Handle 404 errors gracefully (stream may have already ended)
- • Use status callbacks to confirm stream termination
- • Clean up WebSocket connections on the client side when streams stop
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /account-phone-number

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'base-url', title: 'Base URL', level: 2 },
{ id: 'authentication', title: 'Authentication', level: 2 },
{ id: 'operations', title: 'Available Operations', level: 2 }
];
return (
{/* Header Section */}
# Phone Numbers
Manage phone numbers in your Vobiz account. List owned numbers, view inventory, purchase numbers, and release numbers back to inventory.
### Key Features
- List all phone numbers owned by your account with pagination support
- Browse available phone numbers in inventory
- Purchase numbers from inventory and assign to your account
- Release numbers back to inventory when no longer needed
- Master accounts (MA_) can include numbers from sub-accounts
- View detailed number information including capabilities, pricing, and status
{/* Base URL */}
## Base URL
{/* Authentication */}
## Authentication
All Phone Number API endpoints require authentication via `X-Auth-ID` and `X-Auth-Token` headers.
Required Headers:
- • **X-Auth-ID:** Your Auth ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
{/* Available Operations */}
## Available Operations
The PhoneNumber Object
View the complete structure and attributes of a PhoneNumber object including number details, capabilities, billing information, and provider settings.
List Account Phone Numbers
GET request to retrieve all phone numbers owned by your account with pagination support. Master accounts can include numbers from sub-accounts.
List Inventory Numbers
GET request to browse available phone numbers in inventory (not assigned to any account) that are available for purchase.
Purchase from Inventory
POST request to purchase a number from inventory and assign it to your account. Debits balance for setup and monthly fees.
Unrent a Number
DELETE request to release a phone number back to inventory. The number will be unassigned from your account and trunk group.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /account-phone-number/account-phone-number-object

'use client';
const tableOfContents = [
{ id: 'phone-number-object', title: 'The PhoneNumber Object', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'number-status', title: 'Number Status Values', level: 2 },
{ id: 'example', title: 'Example', level: 2 }
];
return (
{/* PhoneNumber Object */}
# The PhoneNumber Object
The PhoneNumber object represents a phone number in the Vobiz system, including details about capabilities, billing, provider information, and status.
{/* Attributes */}
## Attributes
{/* Number Status Values */}
## Number Status Values
Status
Description
active
Number is active and available
pending_purchase
Purchase in progress
pending_release
Release in progress
released
Number has been released
blocked
Number is blocked
{/* Example */}
## Example PhoneNumber Object
```
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"auth_id": "{Auth_ID}",
"e164": "+14155551234",
"country": "US",
"region": "CA",
"capabilities": {
"voice": true,
"sms": true,
"mms": false,
"fax": false
},
"status": "active",
"provider": "vobiz",
"provider_ref": "PN1234567890",
"setup_fee": 1.00,
"monthly_fee": 1.00,
"currency": "USD",
"trunk_group_id": "660e8400-e29b-41d4-a716-446655440001",
"purchased_at": "2025-01-15T10:00:00Z",
"created_at": "2025-01-15T10:00:00Z",
"updated_at": "2025-01-15T10:00:00Z"
}
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /account-phone-number/list-account-phone-numbers

'use client';
const tableOfContents = [
{ id: 'list-numbers', title: 'List Account Phone Numbers', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* List Account Phone Numbers */}
# List Account Phone Numbers
Returns a list of phone numbers that have been purchased and assigned to your account.
API Endpoint
GET
`https://api.vobiz.ai/api/v1/account/{'{auth_id}'}/numbers`
Authentication Required:
- • **X-Auth-ID:** Your Auth ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
{/* Query Parameters */}
## Query Parameters
**Master Accounts (MA_):** For master accounts, setting `include_subaccounts=true` fetches the sub-account list from the Account Service and includes all numbers from SA_ accounts in a single query.
#### cURL - X-Auth-ID & X-Auth-Token
```
curl -X GET "https://api.vobiz.ai/api/v1/account/{AUTH_ID}/numbers" \\
-H "X-Auth-ID: {AUTH_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}"
```
{/* Response */}
## Response Example
```
{
"items": [
{
"id": "90be0b9e-521d-41da-aebd-aba05006272f",
"auth_id": "{Auth_ID}",
"e164": "+918071387149",
"country": "IN",
"region": "Karnataka",
"capabilities": {
"voice": false,
"sms": false,
"mms": false,
"fax": false
},
"status": "active",
"provider": "cloudconnect",
"provider_ref": "",
"trunk_group_id": null,
"setup_fee": 100,
"monthly_fee": 500,
"currency": "INR",
"purchased_at": "2025-10-22T05:04:09.705084Z",
"created_at": "2025-10-21T12:03:44.837733Z",
"updated_at": "2025-10-22T05:04:09.705084Z"
}
],
"page": 1,
"per_page": 25,
"total": 1
}
```
**Response Structure:**
- **items:** Array of phone number objects purchased by your account
- **page:** Current page number
- **per_page:** Number of items per page
- **total:** Total count of purchased phone numbers
**Note:** Only phone numbers with a populated `auth_id` field are returned. Numbers in inventory (with empty auth_id) are not included.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /account-phone-number/list-inventory-numbers

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'query-parameters', title: 'Query Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# List Inventory Numbers
Browse available phone numbers in inventory that are not assigned to any account.
This endpoint lists phone numbers in inventory (auth_id IS NULL) that are available for purchase. These are numbers that can be assigned to your account using the [Purchase from Inventory](/account-phone-number/purchase-from-inventory) endpoint.
**Note:** Only numbers with status='active' and auth_id=NULL are returned. These numbers are ready to be purchased and assigned to your account.
## HTTP Request
GET
/v1/account/{`{auth_id}`}/inventory/numbers
Authentication Required:
- • **X-Auth-ID:** Your Auth ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Query Parameters
## Response
Returns a paginated list of phone numbers available in inventory.
```
{
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"e164": "+14155551234",
"country": "US",
"region": "CA",
"status": "active",
"provider": "manual",
"provider_ref": "MY-CARRIER-123",
"setup_fee": 0.0,
"monthly_fee": 1.0,
"currency": "INR",
"created_at": "2025-01-15T10:00:00Z",
"updated_at": "2025-01-15T10:00:00Z"
}
],
"page": 1,
"per_page": 25,
"total": 500
}
```
## Examples
#### cURL - List All Inventory Numbers
```
curl -X GET "https://api.vobiz.ai/api/v1/account/{AUTH_ID}/inventory/numbers?page=1&per_page=25" \\
-H "X-Auth-ID: {AUTH_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}"
```
#### cURL - Filter by Country
```
curl -X GET "https://api.vobiz.ai/api/v1/account/{AUTH_ID}/inventory/numbers?country=US&page=1&per_page=25" \\
-H "X-Auth-ID: {AUTH_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}"
```
**Use Cases:**
- • Browse available numbers before purchasing
- • Check inventory for specific countries or regions
- • View pricing information for available numbers
- • Find numbers with specific capabilities (voice, SMS, MMS)
**Next Step:** Once you find a number you want, use the [Purchase from Inventory](/account-phone-number/purchase-from-inventory) endpoint to assign it to your account.
);
}

---

# Page: /account-phone-number/purchase-from-inventory

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-body', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Purchase from Inventory
Purchase a phone number from inventory and assign it to your account.
This endpoint purchases a number from inventory and assigns it to your account. The operation debits your account balance for the setup fee and monthly fee.
**Important:** Purchase Process
- Verifies number exists in inventory (auth_id IS NULL)
- Determines billing account (parent MA_ for SA_ accounts)
- Debits balance (setup_fee + monthly_fee)
- Assigns auth_id to your account
- Sets purchased_at timestamp
- Returns updated number
**Note:** If you have insufficient balance, the purchase will fail and the number will remain in inventory. Balance Service is used to debit the amount.
## HTTP Request
POST
/v1/account/{`{auth_id}`}/numbers/purchase-from-inventory
Authentication Required:
- • **X-Auth-ID:** Your Auth ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Request Body
## Response
Returns a success message and the updated PhoneNumber object with auth_id assigned to your account.
```
{
"message": "purchased from inventory",
"number": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"auth_id": "{Auth_ID}",
"e164": "+919876543210",
"country": "IN",
"region": "MH",
"status": "active",
"provider": "manual",
"setup_fee": 0.0,
"monthly_fee": 1.0,
"currency": "USD",
"purchased_at": "2025-01-15T10:00:00Z",
"created_at": "2025-01-15T10:00:00Z",
"updated_at": "2025-01-15T10:00:00Z"
}
}
```
## Examples
#### cURL - Purchase Number from Inventory
```
curl -X POST https://api.vobiz.ai/api/v1/account/{AUTH_ID}/numbers/purchase-from-inventory \\
-H "X-Auth-ID: {AUTH_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}" \\
-H "Content-Type: application/json" \\
-d '{
"e164": "+919876543210",
"currency": "USD"
}'
```
**Error Response (404 Not Found):** If number does not exist in inventory:
```
{
"error": "not found",
"message": "number not found in inventory"
}
```
**Error Response (500 Internal Server Error):** If balance debit fails:
```
{
"error": "internal server error",
"message": "failed to purchase number from provider"
}
```
**Best Practices:**
- • Always check [inventory](/account-phone-number/list-inventory-numbers) first to ensure the number is available
- • Verify you have sufficient balance before purchasing
- • Note that setup_fee + monthly_fee will be debited immediately
- • For sub-accounts (SA_), the parent master account (MA_) will be charged
);
}

---

# Page: /account-phone-number/unrent-number

'use client';
const tableOfContents = [
{ id: 'unrent-number', title: 'Release a Number', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Release a Number */}
# Release a Phone Number
Releases a phone number from your account back to inventory. This operation cannot be undone.
API Endpoint
DELETE
`https://api.vobiz.ai/api/v1/account/{'{auth_id}'}/numbers/{'{e164_number}'}`
Authentication Required:
- • **X-Auth-ID:** Your Auth ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
### Warning  Releasing a phone number is a permanent action that cannot be reversed. Once released, the number returns to inventory and you will lose access to it immediately. Any active calls or configurations using this number will be affected.
{/* Path Parameters */}
## Path Parameters
**e164_number:** The phone number in E.164 format to release (e.g., "+918071387149"). This must be a number currently assigned to your account.
No request body is required for this endpoint.
#### cURL - X-Auth-ID & X-Auth-Token
```
curl -X DELETE "https://api.vobiz.ai/api/v1/account/{AUTH_ID}/numbers/{PHONE_NUMBER}" \\
-H "X-Auth-ID: {AUTH_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}"
```
{/* Response */}
## Response Example
```
{
"message": "number returned to inventory"
}
```
**Success:** The phone number has been released from your account and returned to inventory.
**Changes Made:**
- `auth_id` set to NULL
- `trunk_group_id` set to NULL
- `released_at` timestamp set
- Number becomes available in inventory for purchase
**Error Response (403 Forbidden):** If account does not own this number:
```
{
"error": "forbidden",
"message": "account does not own this number"
}
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /incoming-carrier

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'base-uri', title: 'Base URI', level: 2 },
{ id: 'operations', title: 'Available Operations', level: 2 }
];
return (
{/* Header Section */}
# Incoming Carrier
Incoming Carriers allow you to configure trusted IP addresses for receiving SIP traffic from your carriers/providers. This API enables you to manage carrier configurations, whitelist IP addresses, and control voice traffic settings.
### Key Features
- Configure trusted IP addresses for receiving SIP traffic from carriers/providers
- Whitelist carrier IP addresses for incoming call authentication and security
- Manage multiple incoming carriers with unique 14-character identifiers
- Enable voice traffic per carrier (SMS carriers not supported)
- OpenSIPS integration for real-time IP whitelist updates
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
{/* Base URI */}
## Base URL
**Service:** auris-backend-apis
{/* Available Operations */}
## Available Operations
The IncomingCarrier Object
View the complete structure and attributes of an IncomingCarrier object including carrier ID, IP sets, name, and capability flags.
Create an Incoming Carrier
POST request to add a new incoming carrier to your Vobiz account with specified name and IP addresses.
Retrieve an Incoming Carrier
GET request to retrieve details of a specific incoming carrier including IP configuration and capabilities.
List All Incoming Carriers
GET request to retrieve a list of all incoming carriers registered with your account with optional filtering.
Update an Incoming Carrier
POST request to modify an existing incoming carrier's name and IP address configuration.
Delete an Incoming Carrier
DELETE request to remove an incoming carrier from your account. All numbers associated with the carrier are deleted.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /incoming-carrier/incoming-carrier-object

'use client';
const tableOfContents = [
{ id: 'incoming-carrier-object', title: 'The IncomingCarrier Object', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 }
];
return (
{/* IncomingCarrier Object */}
# The IncomingCarrier Object
The IncomingCarrier object represents a carrier configuration for routing incoming calls through Vobiz from your own phone numbers.
{/* Attributes */}
## Attributes
{/* Example */}
## Example IncomingCarrier Object
```
{
"carrier_id": "a1b2c3d4e5f6g7",
"name": "My Primary Carrier",
"ip_set": "203.0.113.10,203.0.113.11,203.0.113.12",
"voice": true,
"sms": false,
"resource_uri": "/v1/Account/{Auth_ID}/IncomingCarrier/a1b2c3d4e5f6g7/"
}
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /incoming-carrier/create-incoming-carrier

'use client';
const tableOfContents = [
{ id: 'create-carrier', title: 'Create an Incoming Carrier', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Create Incoming Carrier */}
# Create an Incoming Carrier
This API lets you add a new incoming carrier to your Vobiz account.
API Endpoint
POST
`https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/IncomingCarrier/`
{/* Arguments */}
## Arguments
**Note:** IP addresses are added to OpenSIPS IP whitelist in real-time upon carrier creation.
{/* Request Body */}
## Request Body
```
{
"name": "My SIP Carrier",
"ip_set": "203.0.113.10,203.0.113.11,203.0.113.12",
"voice": true,
"sms": false
}
```
## Examples
#### cURL - Create Incoming Carrier
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/IncomingCarrier/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"name": "My SIP Carrier",
"ip_set": "203.0.113.10,203.0.113.11,203.0.113.12",
"voice": true,
"sms": false
}'
```
{/* Response */}
## Response Example
```
{
"api_id": "correlation-id-uuid",
"carrier_id": "a1b2c3d4e5f6g7"
}
```
### Response Fields
- **api_id:** Correlation ID for tracking the request
- **carrier_id:** Unique 14-character identifier for the created carrier
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /incoming-carrier/retrieve-incoming-carrier

'use client';
const tableOfContents = [
{ id: 'retrieve-carrier', title: 'Retrieve an Incoming Carrier', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'returns', title: 'Returns', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Retrieve Incoming Carrier */}
# Retrieve an Incoming Carrier
This API returns the details of an incoming carrier.
API Endpoint
GET
`https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/IncomingCarrier/{'{carrier_id}'}/`
{/* Arguments */}
## Arguments
No arguments need to be passed.
{/* Returns */}
## Returns
Returns an IncomingCarrier object.
{/* Response */}
## Response Example
```
{
"api_id": "correlation-id-uuid",
"carrier_id": "a1b2c3d4e5f6g7",
"name": "My SIP Carrier",
"ip_set": "203.0.113.10,203.0.113.11,203.0.113.12",
"voice": true,
"sms": false,
"resource_uri": "/v1/Account/{Auth_ID}/IncomingCarrier/a1b2c3d4e5f6g7/"
}
```
## Examples
#### cURL - Retrieve Incoming Carrier
```
curl -X GET https://api.vobiz.ai/api/v1/Account/{Auth_ID}/IncomingCarrier/a1b2c3d4e5f6g7/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /incoming-carrier/list-incoming-carriers

'use client';
const tableOfContents = [
{ id: 'list-carriers', title: 'List All Incoming Carriers', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* List All Incoming Carriers */}
# List All Incoming Carriers
This API lists all incoming carriers registered with your account.
API Endpoint
GET
`https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/IncomingCarrier/`
{/* Arguments */}
## Arguments
{/* Response */}
## Response Example
```
{
"api_id": "correlation-id-uuid",
"meta": {
"limit": 20,
"offset": 0,
"total_count": 5
},
"objects": [
{
"carrier_id": "a1b2c3d4e5f6g7",
"name": "Primary Carrier",
"ip_set": "203.0.113.10,203.0.113.11",
"voice": true,
"sms": false,
"resource_uri": "/v1/Account/{Auth_ID}/IncomingCarrier/a1b2c3d4e5f6g7/"
},
{
"carrier_id": "h8i9j0k1l2m3n4",
"name": "Backup Carrier",
"ip_set": "198.51.100.20,198.51.100.21",
"voice": true,
"sms": false,
"resource_uri": "/v1/Account/{Auth_ID}/IncomingCarrier/h8i9j0k1l2m3n4/"
}
]
}
```
## Examples
#### cURL - List All Incoming Carriers
```
curl -X GET https://api.vobiz.ai/api/v1/Account/{Auth_ID}/IncomingCarrier/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /incoming-carrier/update-incoming-carrier

'use client';
const tableOfContents = [
{ id: 'update-carrier', title: 'Update an Incoming Carrier', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Update Incoming Carrier */}
# Update an Incoming Carrier
This API lets you modify an existing incoming carrier set up on your account.
API Endpoint
POST
`https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/IncomingCarrier/{'{carrier_id}'}/`
{/* Arguments */}
## Arguments
### Restrictions
- Cannot enable SMS (sms: true) - SMS carriers not supported
- IP addresses must be valid IPv4 format
- Name must not exceed 255 characters
- Partial update supported - only send fields you want to change
{/* Request Body */}
## Request Body
```
{
"name": "Updated Carrier Name",
"ip_set": "203.0.113.10,203.0.113.20,203.0.113.30"
}
```
## Examples
#### cURL - Update Incoming Carrier
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/IncomingCarrier/a1b2c3d4e5f6g7/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"name": "Updated Carrier Name",
"ip_set": "203.0.113.10,203.0.113.20,203.0.113.30"
}'
```
{/* Response */}
## Response Example
```
{
"api_id": "correlation-id-uuid",
"message": "changed"
}
```
### Response Notes
- **HTTP 202 Accepted:** Update was successful
- **message:** Always returns "changed" on success
- **OpenSIPS:** IP whitelist updated in real-time
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /incoming-carrier/delete-incoming-carrier

'use client';
const tableOfContents = [
{ id: 'delete-carrier', title: 'Delete an Incoming Carrier', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Delete Incoming Carrier */}
# Delete an Incoming Carrier
This API lets you remove an incoming carrier from your account.
API Endpoint
DELETE
`https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/IncomingCarrier/{'{carrier_id}'}/`
### Warning  **This action is permanent and cannot be undone.**
All IP mappings associated with this carrier will be removed from OpenSIPS. Ensure no active SIP traffic is relying on this carrier before deletion.
{/* Arguments */}
## Arguments
No arguments need to be passed.
{/* Response */}
## Response Example
```
{
"api_id": "correlation-id-uuid"
}
```
### Response Notes
- **HTTP 204:** Carrier deleted successfully
- **IP Mappings:** All IP addresses removed from OpenSIPS whitelist
- **Permanent:** This action cannot be undone
## Examples
#### cURL - Delete Incoming Carrier
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{Auth_ID}/IncomingCarrier/a1b2c3d4e5f6g7/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /account

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'base-uri', title: 'Base URI', level: 2 },
{ id: 'operations', title: 'Account Operations', level: 2 }
];
return (
{/* Header Section */}
# Account
The Account object lets you perform actions on your Vobiz account. You can update and modify Account details using this object.
### Key Features
- View account type (standard or developer) and billing mode (prepaid or postpaid)
- Monitor account balance and credit information
- Update account details including name, address, city, state, and timezone
- Access auth credentials and resource URIs for API integration
{/* Base URI */}
## Base URI
{/* Account Operations */}
## Account Operations
The Account Object
View the structure and attributes of the Account object including account type, billing mode, credits, and timezone.
Retrieve Account Details
GET request to retrieve all details of your Vobiz account including balance, auth credentials, and settings.
Update Account Details
POST request to update account information such as name, address, city, state, and timezone.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /account/account-object

'use client';
const tableOfContents = [
{ id: 'account-object', title: 'The Account Object', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 }
];
return (
{/* Account Object */}
# The Account Object
The Account object contains all the information about your Vobiz account, including authentication credentials, pricing tier, verification status, and timestamps.
{/* Attributes */}
## Attributes
{/* Example */}
## Example Account Object
```
{
"id": "MA_SYQRLNIK",
"name": "Your Company Name",
"email": "admin@yourcompany.com",
"description": null,
"auth_id": "hjzz7OuHHokStqvGKQWm35V1u0PBceHP",
"is_active": true,
"is_verified": false,
"country": null,
"created_at": "2025-10-17T08:51:00.552579Z",
"updated_at": "2025-10-22T03:16:11.815251Z",
"last_login": "2025-10-22T03:16:12.901344Z",
"pricing_tier_id": "1fa3db95-526a-4b5e-86a6-4bcd62ef31fa",
"pricing_tier": {
"id": "1fa3db95-526a-4b5e-86a6-4bcd62ef31fa",
"name": "baseTier",
"currency": "INR",
"rate_per_minute": "0.4500",
"billing_increment_seconds": 60,
"minimum_duration_seconds": 0,
"is_active": true,
"is_default": true
}
}
```
### Pricing Tier Object
Each account includes a nested `pricing_tier` object that defines billing rates:
- **rate_per_minute**: Cost per minute of call time in the specified currency
- **billing_increment_seconds**: Granularity of billing (e.g., 60 = billed by full minutes)
- **minimum_duration_seconds**: Minimum billable duration for calls
- **currency**: Currency code (USD, INR, EUR, etc.)
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /account/retrieve-account

'use client';
const tableOfContents = [
{ id: 'retrieve-account', title: 'Retrieve Account Details', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Retrieve Account Details */}
# Retrieve Account Details
GET
`https://api.vobiz.ai/api/v1/auth/me`
Retrieves the complete account details including pricing tier information and authentication credentials.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
{/* Request */}
## Request
```
curl -X GET https://api.vobiz.ai/api/v1/auth/me \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
{/* Arguments */}
## Arguments
No arguments need to be passed.
{/* Response */}
## Response Example
```
{
"name": "Your Company Name",
"email": "admin@yourcompany.com",
"description": null,
"id": "MA_SYQRLNIK",
"auth_id": "hjzz7OuHHokStqvGKQWm35V1u0PBceHP",
"is_active": true,
"is_verified": false,
"created_at": "2025-10-17T08:51:00.552579Z",
"updated_at": "2025-10-22T03:16:11.815251Z",
"last_login": "2025-10-22T03:16:12.901344Z",
"pricing_tier_id": "1fa3db95-526a-4b5e-86a6-4bcd62ef31fa",
"pricing_tier": {
"id": "1fa3db95-526a-4b5e-86a6-4bcd62ef31fa",
"name": "baseTier",
"currency": "INR",
"rate_per_minute": "0.4500",
"billing_increment_seconds": 60,
"minimum_duration_seconds": 0,
"is_active": true,
"is_default": true
}
}
```
**Pricing Tier:** Each account is associated with a pricing tier that determines the per-minute call rate and billing increments. The `pricing_tier` object provides complete details about your account's billing configuration.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /account/update-account

'use client';
const tableOfContents = [
{ id: 'update-account', title: 'Update Account Details', level: 2 },
{ id: 'parameters', title: 'Parameters', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Update Account Details */}
# Update Account Details
POST
`https://api.vobiz.ai/api/v1/Account/{'{auth_id}'}/`
Updates the Account object by setting the values of the parameters passed. Parameters that are not provided will remain unchanged. This request accepts only the name, city, state, time zone, and address as parameters.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
{/* Parameters */}
## Parameters
{/* Request */}
## Request
```
curl -X POST 'https://api.vobiz.ai/api/v1/accounts/{account_id}' \\
--header 'X-Auth-ID: {auth_id}' \\
--header 'X-Auth-Token: {auth_token}' \\
--header 'Content-Type: application/json' \\
--data-raw '{
"name": "John Smith",
"city": "San Francisco",
"address": "123 Main St",
"timezone": "America/Los_Angeles"
}'
```
{/* Request Body */}
## Request Body
```
{
"name": "John Smith",
"city": "San Francisco",
"address": "123 Main St",
"timezone": "America/Los_Angeles"
}
```
{/* Response */}
## Response Example
```
{
"api_id": "02bbdbaa-9303-11e7-8bc8-065f6a74a84a",
"message": "changed"
}
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /account/balance

'use client';
const tableOfContents = [
{ id: 'transactions', title: 'Get Transactions', level: 2 },
{ id: 'balance', title: 'Get Balance', level: 2 },
];
return (
# Balance & Transactions
Retrieve account balance details and transaction history.
{/* Get Transactions */}
## Get Transactions
GET
`https://api.vobiz.ai/api/v1/account/{'{account_id}'}/transactions`
Retrieve a list of transactions for a specific account.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
### Request
```
curl --location 'https://api.vobiz.ai/api/v1/account/YOUR_AUTH_ID/transactions?limit=50&offset=0' \\
--header 'X-Auth-ID: YOUR_AUTH_ID' \\
--header 'X-Auth-Token: YOUR_AUTH_TOKEN' \\
--header 'Accept: application/json'
```
### Response
```
{
"account_id": "MA_XXXXXX",
"count": 50,
"limit": 50,
"offset": 0,
"transactions": [
{
"id": "6883ee37-4085-465f-97c2-e1c67c50aab9",
"account_id": "MA_XXXXXX",
"balance_id": "a84cd3a6-21f4-4b4c-99f2-3d069cb65459",
"type": "debit",
"amount": 0.9,
"currency": "INR",
"description": "Stream session (70s)",
"reference": "cdr:e565c2de-975c-4ba5-b115-44b1042cd397",
"status": "completed",
"processed_at": "2025-12-08T09:38:06.923988Z",
"created_at": "2025-12-08T09:38:06.923988Z",
"updated_at": "2025-12-08T09:38:06.923988Z"
},
{
"id": "6aa3bf01-9158-4f1a-9980-8b3416b57e5a",
"account_id": "MA_XXXXXX",
"balance_id": "a84cd3a6-21f4-4b4c-99f2-3d069cb65459",
"type": "debit",
"amount": 0.45,
"currency": "INR",
"description": "Stream session (30s)",
"reference": "cdr:...",
"status": "completed",
"processed_at": "...",
"created_at": "...",
"updated_at": "..."
}
]
}
```
{/* Get Balance */}
## Get Balance
GET
`https://api.vobiz.ai/api/v1/account/{'{account_id}'}/balance/{'{currency}'}`
Retrieve the balance for a specific account and currency.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
### Request
```
curl --location 'https://api.vobiz.ai/api/v1/account/YOUR_AUTH_ID/balance/INR' \\
--header 'X-Auth-ID: YOUR_AUTH_ID' \\
--header 'X-Auth-Token: YOUR_AUTH_TOKEN' \\
--header 'Accept: application/json'
```
### Response
```
{
"id": "a84cd3a6-21f4-4b4c-99f2-3d069cb65459",
"account_id": "MA_XXXXXX",
"currency": "INR",
"balance": 3082.65,
"reserved_funds": 0,
"available_balance": 3082.65,
"credit_limit": 0,
"low_balance_threshold": 50,
"status": "active",
"created_at": "2025-10-17T08:51:01.646973Z",
"updated_at": "2025-12-08T09:38:06.921968Z"
}
```
);
}

---

# Page: /sub-accounts

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'base-uri', title: 'Base URI', level: 2 },
{ id: 'key-features', title: 'Key Features', level: 2 },
{ id: 'operations', title: 'Subaccount Operations', level: 2 },
{ id: 'use-cases', title: 'Use Cases', level: 2 }
];
return (
{/* Header Section */}
# Subaccounts
You can manage multiple customer accounts using Subaccounts. Subaccounts are owned by a parent Account and can be used to segment, manage, and keep track of the account usage of each user independently.
{/* Base URI */}
## Base URI
{/* Key Features */}
## Key Features
- Complete resource isolation with dedicated auth credentials for secure multi-tenancy
- Independent management of trunks, numbers, CDRs, and balances per subaccount
- Parent account retains full administrative control over all subaccount operations
- Each subaccount receives unique auth_id and auth_token for API access
{/* Subaccount Operations */}
## Subaccount Operations
The Subaccount Object
View the structure and attributes of the Subaccount object including auth credentials, enabled status, and resource URI.
Create a Subaccount
POST request to create a new subaccount with a name and enabled status. Returns unique auth credentials.
Retrieve a Subaccount
GET request to retrieve details of a specific subaccount including auth credentials and settings.
Update a Subaccount
POST request to update subaccount name or enabled status. Disabling blocks all API calls and trunk usage.
Delete a Subaccount
DELETE request to permanently remove a subaccount. Optionally cascade delete or reassociate resources.
List All Subaccounts
GET request to retrieve all subaccounts with pagination support. Sorted by creation date.
{/* Use Cases */}
## Subaccount Use Cases
### Multi-Tenant SaaS
Create a subaccount for each customer. Each customer gets isolated resources and their own API credentials for programmatic access.
### Reseller Model
Create subaccounts for resellers who manage their own customers. Track usage and billing separately per subaccount.
### Department Isolation
Create subaccounts for different departments (Sales, Support, Operations). Each department gets their own trunks and phone numbers.
### Development/Staging
Create subaccounts for dev, staging, and production environments. Test changes in isolation without affecting production.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /sub-accounts/subaccount-object

'use client';
const tableOfContents = [
{ id: 'subaccount-object', title: 'The Subaccount Object', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 }
];
return (
{/* Subaccount Object */}
# The Subaccount Object
The Subaccount object represents an isolated account under your main Vobiz account, with its own authentication credentials, permissions, and rate limiting capabilities.
{/* Attributes */}
## Attributes
{/* Example */}
## Example Subaccount Object
```
{
"name": "Support Team",
"description": "Support-facing voice workload",
"permissions": {
"calls": true,
"cdr": true
},
"rate_limit": 500,
"id": "SA_67401KW8",
"parent_account_id": "{Auth_ID}",
"auth_id": "inG9oUky5uFjdUECaQNzeyVYD6ommaJd",
"is_active": true,
"created_at": "2025-10-22T03:57:35.997500Z",
"updated_at": "2025-10-22T03:57:35.997500Z",
"last_used": null
}
```
**Permissions Object:** The `permissions` object controls what resources the sub-account can access:
- **calls:** Whether the sub-account can make/receive calls
- **cdr:** Whether the sub-account can access Call Detail Records
**Rate Limiting:** The `rate_limit` field controls API request throttling for this sub-account. Set this based on expected usage patterns to prevent abuse.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /sub-accounts/create-subaccount

'use client';
const tableOfContents = [
{ id: 'create-subaccount', title: 'Create a Subaccount', level: 2 },
{ id: 'parameters', title: 'Parameters', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Create Subaccount */}
# Create a Subaccount
POST
`https://api.vobiz.ai/api/v1/accounts/{'{account_id}'}/sub-accounts/`
Creates a new Subaccount object. Provision isolated subaccounts under your main account for multi-tenant SaaS applications, reseller models, or departmental resource segregation.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
{/* Parameters */}
## Parameters
{/* Request */}
## Request
```
curl -X POST 'https://api.vobiz.ai/api/v1/accounts/{account_id}/sub-accounts/' \\
--header 'X-Auth-ID: {auth_id}' \\
--header 'X-Auth-Token: {auth_token}' \\
--header 'Content-Type: application/json' \\
--data-raw '{
"name": "Support Team",
"description": "Support-facing voice workload",
"rate_limit": 500,
"permissions": {
"calls": true,
"cdr": true
},
"password": "S0pport123!"
}'
```
{/* Request Body */}
## Request Body
```
{
"name": "Support Team",
"description": "Support-facing voice workload",
"rate_limit": 500,
"permissions": {
"calls": true,
"cdr": true
},
"password": "S0pport123!"
}
```
{/* Response */}
## Response Example
```
{
"message": "Sub-account created successfully",
"sub_account": {
"name": "Support Team",
"description": "Support-facing voice workload",
"permissions": {
"calls": true,
"cdr": true
},
"rate_limit": 500,
"id": "SA_67401KW8",
"parent_account_id": "{Auth_ID}",
"auth_id": "inG9oUky5uFjdUECaQNzeyVYD6ommaJd",
"is_active": true,
"created_at": "2025-10-22T03:57:35.997500Z",
"updated_at": "2025-10-22T03:57:35.997500Z",
"last_used": null
},
"auth_credentials": {
"auth_id": "inG9oUky5uFjdUECaQNzeyVYD6ommaJd",
"auth_token": "jGZarOpqnCyCWFKA1FWsCnqfcMBMwYxxDKMGh7GzeGM609F0PASeqvg5Nip8Qrf8"
},
"tokens": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJTQV82NzRPMUtXOCIsImFjY291bnRfdHlwZSI6InN1Yl9hY2NvdW50IiwiYXV0aF9pZCI6ImluRzlvVWt5NXVGamRVRUNhUU56ZXlWWUQ2b21tYUpkIiwicmVmcmVzaF90b2tlbl92ZXJzaW9uIjowLCJyb2xlIjoidXNlciIsInBhcmVudF9hY2NvdW50X2lkIjoiTUFfU1lRUkxOMUsiLCJyYXRlX2xpbWl0Ijo1MDAsImV4cCI6MTc2MTEwNzI1NywidHlwZSI6ImFjY2VzcyJ9.ds-ERmtPmbqHARHu3o7olkGCAQfK7QgYXvot2s6nNKo",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJTQV82NzRPMUtXOCIsImFjY291bnRfdHlwZSI6InN1Yl9hY2NvdW50IiwiYXV0aF9pZCI6ImluRzlvVWt5NXVGamRVRUNhUU56ZXlWWUQ2b21tYUpkIiwicmVmcmVzaF90b2tlbl92ZXJzaW9uIjowLCJyb2xlIjoidXNlciIsInBhcmVudF9hY2NvdW50X2lkIjoiTUFfU1lRUkxOMUsiLCJyYXRlX2xpbWl0Ijo1MDAsImV4cCI6MTc2MTcxMDI1NywidHlwZSI6InJlZnJlc2gifQ.y25HxQE_jyG6oa_9CbZQtF2EWCUSXtSzz2scRN_lv4Q",
"token_type": "bearer",
"expires_in": 1800
}
}
```
**Success!** The response contains three important sections:
- **sub_account:** The created sub-account object with all details
- **auth_credentials:** The `auth_id` and `auth_token` for API authentication - save these securely!
- **tokens:** JWT access and refresh tokens for immediate API access
**Security Note:** The `auth_token` is only returned once during creation. Store it securely - you won't be able to retrieve it again. If lost, you'll need to regenerate credentials.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /sub-accounts/retrieve-subaccount

'use client';
const tableOfContents = [
{ id: 'retrieve-subaccount', title: 'Retrieve a Subaccount', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Retrieve Subaccount */}
# Retrieve a Subaccount
GET
`https://api.vobiz.ai/api/v1/accounts/{'{account_id}'}/sub-accounts/{'{sub_account_id}'}`
Retrieves the detail of a specific Subaccount by its ID.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
{/* Request */}
## Request
```
curl -X GET 'https://api.vobiz.ai/api/v1/accounts/{account_id}/sub-accounts/{sub_account_id}' \\
--header 'X-Auth-ID: {auth_id}' \\
--header 'X-Auth-Token: {auth_token}'
```
{/* Arguments */}
## Arguments
No arguments need to be passed.
{/* Response */}
## Response Example
```
{
"name": "Support Team",
"description": "Support-facing voice workload",
"permissions": {
"calls": true,
"cdr": true
},
"rate_limit": 500,
"id": "SA_67401KW8",
"parent_account_id": "{Auth_ID}",
"auth_id": "inG9oUky5uFjdUECaQNzeyVYD6ommaJd",
"is_active": true,
"created_at": "2025-10-22T03:57:35.997500Z",
"updated_at": "2025-10-22T03:57:35.997500Z",
"last_used": null
}
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /sub-accounts/update-subaccount

'use client';
const tableOfContents = [
{ id: 'update-subaccount', title: 'Update a Subaccount', level: 2 },
{ id: 'parameters', title: 'Parameters', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Update Subaccount */}
# Update a Subaccount
PUT
`https://api.vobiz.ai/api/v1/accounts/{'{account_id}'}/sub-accounts/{'{sub_account_id}'}`
Updates the sub-account object by setting the values to the parameters passed. Parameters that are not provided remain unchanged.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Note:** Use this endpoint to update sub-account settings like description, rate limits, or permissions. Setting `is_active=false` would disable the sub-account if that field is supported.
{/* Parameters */}
## Parameters
{/* Request */}
## Request
```
curl -X PUT 'https://api.vobiz.ai/api/v1/accounts/{account_id}/sub-accounts/{sub_account_id}' \\
--header 'X-Auth-ID: {auth_id}' \\
--header 'X-Auth-Token: {auth_token}' \\
--header 'Content-Type: application/json' \\
--data-raw '{
"description": "Updated permissions",
"rate_limit": 750
}'
```
{/* Request Body */}
## Request Body
```
{
"description": "Updated permissions",
"rate_limit": 500
}
```
{/* Response */}
## Response Example
```
{
"name": "Support Team",
"description": "Updated permissions",
"permissions": {
"calls": true,
"cdr": true
},
"rate_limit": 500,
"id": "SA_67401KW8",
"parent_account_id": "{Auth_ID}",
"auth_id": "inG9oUky5uFjdUECaQNzeyVYD6ommaJd",
"is_active": true,
"created_at": "2025-10-22T03:57:35.997500Z",
"updated_at": "2025-10-22T03:59:52.261439Z",
"last_used": null
}
```
**Complete Object Returned:** The response returns the full updated sub-account object, not just a success message. Notice the `updated_at` timestamp has changed to reflect the modification.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /sub-accounts/delete-subaccount

'use client';
const tableOfContents = [
{ id: 'delete-subaccount', title: 'Delete a Subaccount', level: 2 },
{ id: 'parameters', title: 'Parameters', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Delete Subaccount */}
# Delete a Subaccount
DELETE
`https://api.vobiz.ai/api/v1/accounts/{'{account_id}'}/sub-accounts/{'{sub_account_id}'}`
Permanently deletes a Subaccount. This action removes the sub-account and all its associated credentials.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Warning:** Deleting a subaccount is permanent. This action cannot be undone. Ensure you have backed up any necessary data before proceeding.
{/* Request */}
## Request
```
curl -X DELETE 'https://api.vobiz.ai/api/v1/accounts/{account_id}/sub-accounts/{sub_account_id}' \\
--header 'X-Auth-ID: {auth_id}' \\
--header 'X-Auth-Token: {auth_token}'
```
{/* Parameters */}
## Parameters
No request body or parameters required. The sub-account ID is specified in the URL path.
{/* Response */}
## Response Example
```
{
"message": "Sub-account deleted successfully"
}
```
**Success:** The API returns a 200 OK status with a confirmation message when the sub-account is successfully deleted.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /sub-accounts/list-all-subaccounts

'use client';
const tableOfContents = [
{ id: 'list-subaccounts', title: 'List All Subaccounts', level: 2 },
{ id: 'parameters', title: 'Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* List All Subaccounts */}
# List All Subaccounts
GET
`https://api.vobiz.ai/api/v1/accounts/{'{account_id}'}/sub-accounts/`
Returns a paginated list of subaccounts sorted by creation date, with the most recently created subaccount appearing first.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
{/* Parameters */}
## Parameters
{/* Request */}
## Request
```
curl -X GET 'https://api.vobiz.ai/api/v1/accounts/{account_id}/sub-accounts/?page=1&size=25&active_only=true' \\
--header 'X-Auth-ID: {auth_id}' \\
--header 'X-Auth-Token: {auth_token}'
```
{/* Response */}
## Response Example
```
{
"sub_accounts": [
{
"name": "Support Team",
"description": "Support-facing voice workload",
"permissions": {
"calls": true,
"cdr": true
},
"rate_limit": 500,
"id": "SA_67401KW8",
"parent_account_id": "{Auth_ID}",
"auth_id": "inG9oUky5uFjdUECaQNzeyVYD6ommaJd",
"is_active": true,
"created_at": "2025-10-22T03:57:35.997500Z",
"updated_at": "2025-10-22T03:57:35.997500Z",
"last_used": null
}
],
"total": 1,
"page": 1,
"size": 25
}
```
**Pagination:** The response includes pagination metadata at the root level:
- **total:** Total number of sub-accounts matching the filter
- **page:** Current page number
- **size:** Number of results per page
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /applications

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'key-concepts', title: 'Key Concepts', level: 2 },
{ id: 'operations', title: 'Application Operations', level: 2 },
{ id: 'webhook-callbacks', title: 'Webhook Callbacks', level: 2 },
{ id: 'best-practices', title: 'Best Practices', level: 2 }
];
return (
{/* Header Section */}
# Applications
An Application is a set of Answer, Hangup, and Message URLs that help you control your incoming calls and messages.
{/* Key Concepts */}
## Key Concepts
### Answer URL
Vobiz requests this URL for a valid Vobiz XML element on an incoming call. The XML returned by this URL determines the flow of the call.
### Hangup URL
Vobiz will make an HTTP request to this URL when the call is hung up. Useful for call analytics and cleanup operations.
### Message URL
Vobiz will send all incoming messages to this URL. We expect to receive an HTTP status code of 200 from this URL.
### SIP URI
All Vobiz applications can be called directly without attaching them to a number or an endpoint. When an incoming call is received on this URI, Vobiz follows the same flow as it does with a number or an endpoint.
{/* Application Operations */}
## Application Operations
The Application Object
View the structure and attributes of the Application object including URLs, methods, and default settings.
Create an Application
POST request to create a new application with answer URL, hangup URL, and message URL configuration.
Retrieve an Application
GET request to retrieve all details of a specific application by app_id.
Update an Application
POST request to modify application settings. Unspecified parameters remain unchanged.
Delete an Application
DELETE request to permanently remove an application. Optionally cascade delete associated endpoints.
List All Applications
GET request to retrieve all applications with optional filtering and pagination support.
Link Numbers
Manage associations between phone numbers and voice applications (Attach/Detach).
{/* Webhook Callbacks */}
## Webhook Callbacks
{/* Answer URL Callback */}
### Answer URL Callback
When a call is answered, Vobiz makes a request to your `answer_url` with call details.
Request Parameters:
{`POST https://example.com/answer Content-Type: application/x-www-form-urlencoded CallUUID=abc123&From=14155551234&To=14155556789&Direction=inbound&CallStatus=ringing`}    Expected Response (XML):
{`  Welcome to our service  Press 1 for sales, 2 for support  `}    {/* Hangup URL Callback */}  ### Hangup URL Callback  When a call ends, Vobiz notifies your `hangup_url` with call details and duration.
Request Parameters:
{`POST https://example.com/hangup Content-Type: application/x-www-form-urlencoded CallUUID=abc123&CallStatus=completed&Duration=45&HangupCause=NORMAL_CLEARING`}      {/* Best Practices */}  ## Best Practices         #### Always Use HTTPS All webhook URLs (answer_url, hangup_url, etc.) must use HTTPS for security.
#### Handle Retries Vobiz retries failed webhook calls up to 3 times. Ensure idempotent operations.
#### Respond Quickly Answer URL must respond within 10 seconds to avoid call timeout.
#### Validate Webhooks Verify requests are from Vobiz using signature validation.
#### Use Fallback URLs Always configure fallback_answer_url for production apps to handle failures.
#### Test in Development Use test account before deploying to production environment.
#### Monitor Usage Check which numbers/endpoints use each app before deletion.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /applications/application-object

'use client';
const tableOfContents = [
{ id: 'application-object', title: 'The Application Object', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 }
];
return (
{/* Application Object */}
# The Application Object
The Application object contains all configuration for call and message handling, including URL endpoints and HTTP methods.
{/* Attributes */}
## Attributes
{/* Example */}
## Example Application Object
```
{
"api_id": "550e8400-e29b-41d4-a716-446655440000",
"app_id": "12345678",
"app_name": "My Voice Application",
"answer_url": "https://example.com/answer",
"answer_method": "POST",
"hangup_url": "https://example.com/hangup",
"hangup_method": "POST",
"fallback_answer_url": "https://example.com/fallback",
"fallback_method": "POST",
"message_url": "https://example.com/message",
"message_method": "POST",
"default_number_app": false,
"default_endpoint_app": false,
"sub_account": null,
"resource_uri": "/v1/Account/{Auth_ID}/Application/12345678/",
"created_at": "2025-10-28T10:30:00Z",
"updated_at": "2025-10-28T10:30:00Z"
}
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /applications/create-application

'use client';
const tableOfContents = [
{ id: 'create-application', title: 'Create an Application', level: 2 },
{ id: 'parameters', title: 'Parameters', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Create Application */}
# Create an Application
POST
`https://api.vobiz.ai/api/v1/Account/{'{authID}'}/Application/`
Creates an Application with webhook URLs for call handling. Creating an application is usually a first step, after which you attach the application to either a number or an endpoint.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
{/* Parameters */}
## Parameters
{/* Request Body */}
## Request Body
```
{
"app_name": "My Voice Application",
"answer_url": "https://example.com/answer",
"answer_method": "POST",
"hangup_url": "https://example.com/hangup",
"hangup_method": "POST",
"fallback_answer_url": "https://example.com/fallback",
"fallback_method": "POST",
"message_url": "https://example.com/message",
"message_method": "POST",
"default_number_app": false,
"default_endpoint_app": false,
"sub_account": null
}
```
{/* Response */}
## Response Examples
```
{
"api_id": "550e8400-e29b-41d4-a716-446655440000",
"message": "created",
"app_id": "12345678",
"resource_uri": "/v1/Account/{Auth_ID}/Application/12345678/"
}
```
```
{
"error": "invalid request parameters",
"details": {
"app_name": "This field is required",
"answer_url": "Enter a valid URL"
}
}
```
### cURL Example
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Application/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"app_name": "My IVR System",
"answer_url": "https://myapp.com/ivr/answer",
"answer_method": "POST"
}'
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /applications/retrieve-application

'use client';
const tableOfContents = [
{ id: 'retrieve-application', title: 'Retrieve an Application', level: 2 },
{ id: 'arguments', title: 'Arguments', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Retrieve Application */}
# Retrieve an Application
GET
`https://api.vobiz.ai/api/v1/Account/{'{authID}'}/Application/{'{appID}'}/`
Get details of a particular application by passing the app_id. This API returns all the information linked with the application.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
{/* Arguments */}
## Arguments
No request parameters needed.
{/* Response */}
## Response Examples
```
{
"api_id": "550e8400-e29b-41d4-a716-446655440000",
"app_id": "12345678",
"app_name": "My Voice Application",
"answer_url": "https://example.com/answer",
"answer_method": "POST",
"hangup_url": "https://example.com/hangup",
"hangup_method": "POST",
"fallback_answer_url": "https://example.com/fallback",
"fallback_method": "POST",
"message_url": "https://example.com/message",
"message_method": "POST",
"default_number_app": false,
"default_endpoint_app": false,
"sub_account": null,
"resource_uri": "/v1/Account/{Auth_ID}/Application/12345678/",
"created_at": "2025-10-28T10:30:00Z",
"updated_at": "2025-10-28T10:30:00Z"
}
```
```
{
"error": "Application not found",
"app_id": "99999999"
}
```
### cURL Example
```
curl -X GET https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Application/12345678/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /applications/update-application

'use client';
const tableOfContents = [
{ id: 'update-application', title: 'Update an Application', level: 2 },
{ id: 'parameters', title: 'Parameters', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Update Application */}
# Update an Application
POST
`https://api.vobiz.ai/api/v1/Account/{'{authID}'}/Application/{'{appID}'}/`
Modify an application using this API. You can update any subset of fields (partial update).
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
Important Notes:
- • Fields not provided will remain unchanged
- • **sub_account** cannot be changed after creation
{/* Parameters */}
## Parameters
{/* Request Body */}
## Request Body
```
{
"app_name": "Updated Application Name",
"answer_url": "https://example.com/updated-answer",
"answer_method": "POST",
"hangup_url": "https://example.com/updated-hangup",
"hangup_method": "POST",
"fallback_answer_url": "https://example.com/updated-fallback",
"fallback_method": "POST",
"message_url": "https://example.com/updated-message",
"message_method": "POST",
"default_number_app": true,
"default_endpoint_app": false
}
```
{/* Response */}
## Response Examples
```
{
"api_id": "550e8400-e29b-41d4-a716-446655440000",
"message": "changed",
"app_id": "12345678",
"resource_uri": "/v1/Account/{Auth_ID}/Application/12345678/"
}
```
```
{
"error": "invalid request parameters",
"details": {
"answer_url": "Enter a valid URL"
}
}
```
```
{
"error": "Application not found",
"app_id": "99999999"
}
```
### cURL Example
```
curl -X POST https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Application/12345678/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"app_name": "Updated IVR System",
"default_number_app": true
}'
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /applications/delete-application

'use client';
const tableOfContents = [
{ id: 'delete-application', title: 'Delete an Application', level: 2 },
{ id: 'parameters', title: 'Parameters', level: 2 },
{ id: 'request', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* Delete Application */}
# Delete an Application
DELETE
`https://api.vobiz.ai/api/v1/Account/{'{authID}'}/Application/{'{appID}'}/`
This API deletes an Application permanently.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
Warning:
Deleting an application is permanent and cannot be undone. If the application is associated with phone numbers, the deletion may be blocked unless those associations are removed first.
{/* Parameters */}
## Arguments
No request parameters needed.
{/* Response */}
## Response Examples
### Success Response (204 No Content)
(No response body)
```
{
"error": "Application not found",
"app_id": "99999999"
}
```
```
{
"error": "Cannot delete application",
"message": "Application is currently in use by 5 phone numbers"
}
```
### cURL Example
```
curl -X DELETE https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Application/12345678/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /applications/list-all-applications

'use client';
const tableOfContents = [
{ id: 'list-applications', title: 'List All Applications', level: 2 },
{ id: 'parameters', title: 'Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 }
];
return (
{/* List All Applications */}
# List All Applications
GET
`https://api.vobiz.ai/api/v1/Account/{'{authID}'}/Application/`
This API is used to get details of all the application that have been created under your Vobiz account.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
{/* Parameters */}
## Parameters
{/* Response */}
## Response Example
```
{
"api_id": "550e8400-e29b-41d4-a716-446655440000",
"meta": {
"limit": 20,
"offset": 0,
"total_count": 45
},
"objects": [
{
"app_id": "12345678",
"app_name": "My Voice Application",
"answer_url": "https://example.com/answer",
"answer_method": "POST",
"hangup_url": "https://example.com/hangup",
"hangup_method": "POST",
"fallback_answer_url": "https://example.com/fallback",
"fallback_method": "POST",
"message_url": "https://example.com/message",
"message_method": "POST",
"default_number_app": false,
"default_endpoint_app": false,
"sub_account": null,
"resource_uri": "/v1/Account/{Auth_ID}/Application/12345678/",
"created_at": "2025-10-28T10:30:00Z",
"updated_at": "2025-10-28T10:30:00Z"
},
{
"app_id": "87654321",
"app_name": "Customer Service App",
"answer_url": "https://example.com/cs/answer",
"answer_method": "GET",
"hangup_url": null,
"hangup_method": null,
"fallback_answer_url": null,
"fallback_method": null,
"message_url": null,
"message_method": null,
"default_number_app": true,
"default_endpoint_app": false,
"sub_account": null,
"resource_uri": "/v1/Account/{Auth_ID}/Application/87654321/",
"created_at": "2025-10-27T15:20:00Z",
"updated_at": "2025-10-28T08:15:00Z"
}
]
}
```
### cURL Example
```
curl -X GET "https://api.vobiz.ai/api/v1/Account/{Auth_ID}/Application/?limit=20&offset=0" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /applications/link-numbers

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attach-number', title: 'Attach Number to Application', level: 2 },
{ id: 'detach-number', title: 'Detach Number from Application', level: 2 }
];
return (
{/* Introduction */}
# Link Numbers
Manage the association between your phone numbers and voice applications. You can attach a number to an application to handle incoming calls, or detach it to remove the association.
{/* Attach Number */}
## Attach Number to Application
POST
`https://api.vobiz.ai/api/v1/account/{'{authID}'}/numbers/{'{number}'}/application`
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
### Parameters
### Example Request
```
curl -X POST "https://api.vobiz.ai/api/v1/account/{Auth_ID}/numbers/%2B1234567890/application" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"application_id": "app_xxxxxxxxxxxx"
}'
```
### Response
```
{
"message": "Number linked successfully",
"number": "+1234567890",
"application_id": "app_xxxxxxxxxxxx"
}
```
{/* Detach Number */}
## Detach Number from Application
DELETE
`https://api.vobiz.ai/api/v1/account/{'{authID}'}/numbers/{'{number}'}/application`
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
### Parameters
### Example Request
```
curl -X DELETE "https://api.vobiz.ai/api/v1/account/{Auth_ID}/numbers/%2B1234567890/application" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
### Response
```
{
"message": "Number detached successfully",
"number": "+1234567890"
}
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /trunks

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'key-features', title: 'Key Features', level: 2 },
{ id: 'trunk-management', title: 'Trunk Management', level: 2 },
{ id: 'credentials', title: 'Credentials', level: 2 },
{ id: 'ip-acl', title: 'IP Access Control', level: 2 },
{ id: 'origination-uri', title: 'Origination URIs', level: 2 },
{ id: 'authentication', title: 'Authentication Methods', level: 2 },
{ id: 'getting-started', title: 'Getting Started', level: 2 }
];
return (
{/* Header Section */}
# SIP Trunk Service
Manage SIP trunks for enterprise voice communications. Create trunks with automatic SIP domain provisioning, configure authentication methods, and set up outbound routing for scalable telephony infrastructure.
### What is a SIP Trunk?
A SIP trunk is a virtual connection that enables voice communication over IP networks. Each trunk serves as a dedicated voice gateway with its own authentication, rate limits, and routing configuration. Vobiz automatically provisions each trunk with a unique SIP domain and integrates it with Kamailio for robust SIP routing and authentication.
- **Auto-generated SIP domains:** Each trunk gets a unique domain like `trunkId.sip.vobiz.ai`
- **Flexible authentication:** Support for both username/password and IP-based authentication
- **Rate limiting:** Configure concurrent call limits and calls-per-second (CPS) throttling
- **Outbound routing:** Define origination URIs with priority-based failover and load balancing
{/* Key Features */}
## Key Features
### Dual Authentication  Choose between username/password credentials or IP whitelisting. Combine both methods for maximum security.
### Intelligent Routing  Configure multiple origination URIs with priority-based failover and weight-based load balancing for resilient outbound calling.
### Rate Limiting  Protect against traffic spikes with configurable concurrent call limits and calls-per-second (CPS) throttling.
### Kamailio Integration  Seamless integration with Kamailio SIP proxy for robust routing, authentication, and load balancing infrastructure.
{/* Trunk Management */}
## Trunk Management
The core trunk operations allow you to create, configure, and manage your SIP trunks. Each trunk acts as an independent voice gateway with its own configuration and rate limits.
#### The Trunk Object
Complete structure and attributes of a trunk
#### Create a Trunk Provision a new SIP trunk with auto-generated domain
#### Retrieve a Trunk Get details of a specific trunk by ID
#### Retrieve All Trunks List all trunks with pagination support
#### Update a Trunk Modify trunk configuration and rate limits
#### Delete a Trunk Permanently remove a trunk and its resources
{/* Credentials */}  ## Credentials   Credentials provide username/password authentication for your SIP trunk. You can create multiple credentials per trunk for different devices or use cases. Passwords are securely hashed and never returned in API responses after creation.
View Credentials Documentation
{/* IP ACL */}  ## IP Access Control Lists   IP Access Control Lists (IP ACLs) enable IP-based authentication by whitelisting specific IPv4 addresses. Devices calling from whitelisted IPs can use the trunk without password authentication. This is ideal for PBX systems, SIP gateways, and carrier interconnections with static IP addresses.
View IP ACL Documentation
{/* Origination URI */}  ## Origination URIs   Origination URIs define where outbound calls from your trunk should be routed. Configure multiple URIs with priority-based failover (lower priority tried first) and weight-based load balancing (higher weight receives more traffic). This enables resilient, distributed call routing with automatic failover.
View Origination URI Documentation
{/* Authentication Methods */}  ## Authentication Methods   ### Username/Password  SIP digest authentication using credentials. Ideal for devices with dynamic IP addresses or mobile softphones. Kamailio validates credentials against the subscriber database.
Works from any IP address      Multiple credentials per trunk      Secure password hashing     ### IP Whitelisting  IP-based authentication without passwords. Best for PBX systems, SIP gateways, and carrier connections with static IP addresses. Provides higher security for production deployments.
No password required      Enhanced security      Requires static IP addresses      {/* Getting Started */}  ## Getting Started  ### Quick Setup Guide   1  #### Create a Trunk Use the [Create Trunk](/trunks/create-trunk) endpoint to provision a new SIP trunk. You'll receive a unique SIP domain and trunk ID.
2
#### Configure Authentication
Add [credentials](/trunks/credentials) for password authentication or configure [IP ACLs](/trunks/ip-acl) for IP-based authentication.
3
#### Set Up Routing
Configure [origination URIs](/trunks/origination-uri) to define where outbound calls should be routed. Set priorities for failover and weights for load balancing.
4
#### Test Your Trunk
Configure your SIP client with the trunk's domain and credentials, then make a test call to verify everything is working correctly.
);
}

---

# Page: /trunks/trunk-object

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 }
];
return (
# The Trunk Object
Complete structure and attributes of a SIP Trunk object.
The Trunk object represents a SIP trunking connection in your account. A trunk provides the foundation for voice communication by managing authentication, rate limiting, and routing configuration. Each trunk can have multiple credentials, IP access control lists, and origination URIs to support various use cases.
**Auto-Generated SIP Domain:** When a trunk is created, Vobiz automatically generates a unique SIP domain in the format: `trunkId.sip.vobiz.ai`. This domain is used for inbound call routing to your trunk.
## Attributes
## Example
#### Trunk Object Response
A typical trunk object as returned by the API:
```
{
"trunk_id": "bfab10fb-cb97-488b-9c63-989c32980b0f",
"account_id": "{Auth_ID}",
"name": "Production Trunk",
"description": "Main production SIP trunk for US East region",
"concurrent_calls_limit": 100,
"cps_limit": 10,
"enabled": true,
"created_at": "2025-01-15T10:30:45Z",
"updated_at": "2025-01-20T14:22:10Z"
}
```
**Rate Limiting:** The `concurrent_calls_limit` and `cps_limit` protect your trunk from overload and help manage costs.
**Timestamps:** All timestamps are in UTC timezone following ISO 8601 format.
);
}

---

# Page: /trunks/create-trunk

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Create a Trunk
Create a new SIP trunk for voice communications.
This API allows you to create a new SIP trunk for handling voice traffic. Each trunk can be configured with rate limits, authentication methods (credentials and IP ACLs), and origination URIs for outbound routing.
**Auto-Generated Domain:** Upon creation, Vobiz automatically generates a unique SIP domain for your trunk in the format: `trunk_id.sip.vobiz.ai`. This domain is used for routing inbound calls to your trunk.
## HTTP Request
POST
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/trunks
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Request Parameters
## Response
Returns the complete trunk object including the auto-generated `trunk_id` UUID and timestamps.
```
{
"trunk_id": "aabbcc-dd-ee-ff-gg",
"account_id": "MA_XYZ123",
"name": "My SIP Trunk",
"trunk_domain": "sip.example.com",
"trunk_status": "active",
"secure": false,
"trunk_direction": "outbound",
"concurrent_calls_limit": 10,
"cps_limit": 5,
"ipacl_uuid": "YOUR_IP_ACL_ID",
"credential_uuid": "YOUR_CREDENTIAL_ID",
"primary_uri_uuid": "YOUR_PRIMARY_URI_ID",
"fallback_uri_uuid": "YOUR_FALLBACK_URI_ID",
"transport": "udp",
"created_at": "2025-11-03T14:09:12.08032875Z",
"updated_at": "2025-11-03T14:09:12.08032875Z"
}
```
## Examples
#### cURL - Basic Trunk
```
curl -X POST https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"name": "My SIP Trunk",
"trunk_status": "enabled",
"secure": false,
"trunk_direction": "outbound",
"trunk_domain": "sip.example.com",
"concurrent_calls_limit": 10,
"cps_limit": 5,
"transport": "udp",
"ipacl_uuid": "{ipAclId}",
"credential_uuid": "{credentialId}",
"primary_uri_uuid": "{primaryUriId}",
"fallback_uri_uuid": "{fallbackUriId}",
"inbound_destination": "sip:user@host.com"
}'
```
**Next Steps:**
- • Save the `trunk_id` for all future operations
- • Add credentials or IP ACLs for authentication
- • Configure origination URIs for outbound call routing
- • Test the trunk with a sample call before production use
);
}

---

# Page: /trunks/retrieve-trunk

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Retrieve a Trunk
Get details of a specific SIP trunk by ID.
This API retrieves the complete details of a specific trunk using its unique trunk_id. Use this endpoint to verify trunk configuration, check rate limits, or confirm the trunk's enabled status.
## HTTP Request
GET
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/trunks/{`{trunk_id}`}
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Response
Returns the complete trunk object with all attributes.
```
{
"trunk_id": "22fed784-4ed9-4caf-8bbd-7738ca37f275",
"account_id": "{Auth_ID}",
"name": "US Primary",
"trunk_domain": "22fed784.sip.vobiz.ai",
"trunk_status": "active",
"secure": false,
"trunk_direction": "both",
"concurrent_calls_limit": 20,
"cps_limit": 10,
"ipacl_uuid": "ip-acl-uuid-123",
"credential_uuid": "cred-uuid-123",
"primary_uri_uuid": "uri-uuid-123",
"fallback_uri_uuid": "uri-uuid-456",
"description": "Primary outbound trunk",
"inbound_destination": "5hj19p4hixv.sip.livekit.cloud",
"transport": "udp",
"created_at": "2025-10-17T11:17:46.06043Z",
"updated_at": "2025-10-27T11:31:21.799571Z"
}
```
## Examples
#### cURL
```
curl -X GET https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks/bfab10fb-cb97-488b-9c63-989c32980b0f \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Error Response (404):** If the trunk_id doesn't exist or doesn't belong to your account, you'll receive a 404 Not Found error.
);
}

---

# Page: /trunks/retrieve-all-trunks

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'query-parameters', title: 'Query Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Retrieve All Trunks
List all SIP trunks for your account with pagination support.
This API retrieves a paginated list of all trunks associated with your account. Use this endpoint to view all your trunk configurations, monitor resource usage, and manage multiple trunks.
## HTTP Request
GET
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/trunks
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Query Parameters
## Response
Returns a paginated list of trunk objects with metadata about pagination state.
```
{
"meta": {
"limit": 10,
"offset": 0,
"total_count": 2
},
"objects": [
{
"trunk_id": "08c9431-fc2b-4a9e-997e-1b0fcd913565",
"account_id": "{Auth_ID}",
"name": "US Primary",
"trunk_domain": "08c9431.sip.vobiz.ai",
"trunk_status": "active",
"secure": false,
"trunk_direction": "both",
"concurrent_calls_limit": 20,
"cps_limit": 10,
"ipacl_uuid": "ip-acl-uuid-123",
"credential_uuid": "cred-uuid-123",
"primary_uri_uuid": "uri-uuid-123",
"fallback_uri_uuid": "uri-uuid-456",
"description": "Primary outbound trunk",
"inbound_destination": "5hj19p4hixv.sip.livekit.cloud",
"transport": "udp",
"created_at": "2025-10-17T11:18:06.869912Z",
"updated_at": "2025-10-28T10:15:09.12671Z"
},
{
"trunk_id": "22fed784-4ed9-4caf-8bbd-7738ca37f275",
"account_id": "{Auth_ID}",
"name": "US Primary",
"trunk_domain": "22fed784.sip.vobiz.ai",
"trunk_status": "active",
"secure": false,
"trunk_direction": "both",
"concurrent_calls_limit": 20,
"cps_limit": 10,
"ipacl_uuid": "ip-acl-uuid-789",
"credential_uuid": "cred-uuid-789",
"description": "Primary outbound trunk",
"inbound_destination": "5hj19p4hixv.sip.livekit.cloud",
"transport": "udp",
"created_at": "2025-10-17T11:17:46.06043Z",
"updated_at": "2025-10-27T11:31:21.799571Z"
}
]
}
```
## Examples
#### cURL - Default Pagination
```
curl -X GET "https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### cURL - Custom Pagination
```
curl -X GET "https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks?limit=50&offset=0" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Pagination Tip:** Use `total_count` from the meta object to calculate total pages. For page 2 with limit 10, use offset=10.
);
}

---

# Page: /trunks/update-trunk

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Update a Trunk
Modify configuration settings for an existing SIP trunk.
This API allows you to update the configuration of an existing trunk. You can modify the name, description, and rate limits. Only include fields you want to update; other fields will remain unchanged.
**Note:** The `trunk_id` and `account_id` cannot be changed after creation.
## HTTP Request
PUT
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/trunks/{`{trunk_id}`}
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Request Parameters
All parameters are optional. Only include fields you want to update.
## Response
Returns the complete updated trunk object with the new `updated_at` timestamp.
```
{
"trunk_id": "aabbcc-dd-ee-ff-gg",
"account_id": "MA_XYZ123",
"name": "Updated Production Trunk",
"trunk_domain": "aabbcc.sip.vobiz.ai",
"trunk_status": "active",
"secure": false,
"trunk_direction": "both",
"username": "testuser",
"password": "TestPassword123!",
"concurrent_calls_limit": 10,
"cps_limit": 2,
"ip_whitelist": [
"198.51.100.10",
"10.0.0.0/8"
],
"credential_uuid": "xyz-abc-123",
"description": "Updated description for production trunk",
"transport": "udp",
"created_at": "2025-11-03T14:09:12.08032875Z",
"updated_at": "2025-11-03T14:10:15.12345678Z"
}
```
## Examples
#### cURL - Update Name Only
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks/bfab10fb-cb97-488b-9c63-989c32980b0f \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"name": "Updated Production Trunk"
}'
```
#### cURL - Disable Trunk
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks/bfab10fb-cb97-488b-9c63-989c32980b0f \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"enabled": false
}'
```
**Best Practice:** Disable a trunk instead of deleting it if you might need the configuration later. Disabled trunks won't handle calls but preserve all settings, credentials, and routing rules.
);
}

---

# Page: /trunks/assign-number

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'url-parameters', title: 'URL Parameters', level: 2 },
{ id: 'request-body', title: 'Request Body', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Assign Number to Trunk
Link a phone number to a specific SIP Trunk for call routing.
This API endpoint allows you to assign a phone number to a specific SIP trunk. Once assigned, all inbound calls to that phone number will be routed through the designated trunk according to your trunk's configuration.
**Important:** The phone number must already be in your account inventory. You can purchase numbers using the [Purchase Number](/account-phone-number/purchase-from-inventory) endpoint before assigning them to a trunk.
## HTTP Request
POST
https://api.vobiz.ai/api/v1/account/{`{ACCOUNT_ID}`}/numbers/{`{PHONE_NUMBER}`}/assign
URL Encoding Notice:
Always encode the phone number in the URL. Use `%2B` instead of the `+` symbol. For example: `%2B912271264217` (not +912271264217). Failure to encode properly may result in a 404 error.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., MA_BN2MZ1VV)
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## URL Parameters
## Request Body
```
{
"trunk_group_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
## Response
On successful assignment, the API returns a `204 No Content` status with no response body. This indicates the number has been successfully linked to the trunk.
```
HTTP/1.1 204 No Content
Date: Thu, 23 Jan 2026 07:07:24 GMT
Server: Vobiz API Gateway
```
#### Error Responses
```
{
"error": "Number not found",
"message": "The phone number could not be found. Ensure it is URL-encoded correctly."
}
```
```
{
"error": "invalid request",
"message": "This number is already assigned to a trunk."
}
```
## Examples
#### cURL - Assign Number to Trunk
```
curl -X POST "https://api.vobiz.ai/api/v1/account/{ACCOUNT_ID}/numbers/%2B1234567890/assign" \\
-H "X-Auth-ID: {ACCOUNT_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}" \\
-H "Content-Type: application/json" \\
-d '{
"trunk_group_id": "{TRUNK_ID}"
}'
```
#### Generic Template (Use Your Own Values)
```
curl -X POST "https://api.vobiz.ai/api/v1/account/{ACCOUNT_ID}/numbers/{PHONE_NUMBER}/assign" \\
-H "X-Auth-ID: {ACCOUNT_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}" \\
-H "Content-Type: application/json" \\
-d '{
"trunk_group_id": "{TRUNK_ID}"
}'
```
**Quick Tips:**
- • **Success Code:** Look for `204 No Content` response
- • **URL Encoding:** Always use `%2B` instead of `+` in the phone number
- • **Trunk UUID:** Get the trunk_group_id from the [Create Trunk](/trunks/create-trunk) response
- • **Number Format:** Use E.164 format with country code (e.g., +1234567890)
**Next Steps:**
- • Verify the assignment by retrieving your trunk details
- • Configure your trunk's inbound routing rules
- • Test inbound calls to the assigned number
- • To remove the assignment, use the [Unassign Number](/trunks/unassign-number) endpoint
);
}

---

# Page: /trunks/unassign-number

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'url-parameters', title: 'URL Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Unassign Number from Trunk
Remove the link between a phone number and a SIP trunk.
This API endpoint allows you to remove the assignment between a phone number and a SIP trunk. After unassignment, the number will remain in your account inventory but will no longer route calls through the previously assigned trunk.
**Warning:** Unassigning a number from a trunk will immediately stop routing inbound calls to that number. Ensure you have an alternative routing configuration or reassign the number to a different trunk if you want to continue receiving calls.
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/account/{`{ACCOUNT_ID}`}/numbers/{`{PHONE_NUMBER}`}/assign
URL Encoding Notice:
Always encode the phone number in the URL. Use `%2B` instead of the `+` symbol. For example: `%2B912271264217` (not +912271264217). Failure to encode properly may result in a 404 error.
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., MA_BN2MZ1VV)
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
**Note:** This endpoint uses the `DELETE` HTTP method on the same URL path as the assignment endpoint. No request body is required.
## URL Parameters
**No Request Body Required:** The DELETE method does not require a request body. The phone number specified in the URL will be unassigned from its currently associated trunk.
## Response
On successful unassignment, the API returns a `204 No Content` status with no response body. This indicates the number has been successfully unlinked from the trunk.
```
HTTP/1.1 204 No Content
Date: Thu, 23 Jan 2026 07:07:24 GMT
Server: Vobiz API Gateway
```
#### Error Responses
```
{
"error": "Number not found",
"message": "The phone number could not be found or is not assigned to any trunk."
}
```
```
{
"error": "invalid request",
"message": "The phone number format is invalid. Ensure it is URL-encoded correctly."
}
```
## Examples
#### cURL - Unassign Number from Trunk
```
curl -X DELETE "https://api.vobiz.ai/api/v1/account/{ACCOUNT_ID}/numbers/%2B1234567890/assign" \\
-H "X-Auth-ID: {ACCOUNT_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}" \\
-H "Content-Type: application/json"
```
#### Generic Template (Use Your Own Values)
```
curl -X DELETE "https://api.vobiz.ai/api/v1/account/{ACCOUNT_ID}/numbers/{PHONE_NUMBER}/assign" \\
-H "X-Auth-ID: {ACCOUNT_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}" \\
-H "Content-Type: application/json"
```
**Quick Tips:**
- • **Success Code:** Look for `204 No Content` response
- • **URL Encoding:** Always use `%2B` instead of `+` in the phone number
- • **No Request Body:** DELETE requests do not require a request body
- • **Number Format:** Use E.164 format with country code (e.g., +1234567890)
**Important Considerations:**
- • **Immediate Effect:** Unassignment takes effect immediately; inbound calls will no longer route
- • **Number Retention:** The number remains in your account inventory after unassignment
- • **Reassignment:** You can reassign the number to a different trunk or the same trunk later
- • **Billing:** Number rental charges continue until you release the number using the [Unrent Number](/account-phone-number/unrent-number) endpoint
**Next Steps:**
- • Reassign to a different trunk using the [Assign Number](/trunks/assign-number) endpoint
- • Or, release the number entirely using the [Unrent Number](/account-phone-number/unrent-number) endpoint
- • Verify the unassignment by listing your trunk details
- • Update your application logic to handle the routing change
);
}

---

# Page: /trunks/delete-trunk

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Delete a Trunk
Permanently remove a SIP trunk and all its associated resources.
This API permanently deletes a trunk and all its associated resources including credentials, IP ACL entries, and origination URIs. This action cannot be undone.
**Warning:** Deleting a trunk will:
- • Permanently delete all credentials associated with this trunk
- • Remove all IP ACL entries
- • Delete all origination URIs
- • Immediately stop all active calls on this trunk
- • Make the trunk's SIP domain unavailable for inbound calls
**Alternative:** Consider disabling the trunk instead (set `enabled: false`) to preserve configuration while preventing new calls.
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/trunks/{`{trunk_id}`}
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Response
Returns HTTP 204 No Content on successful deletion. No response body is returned.
```
curl -X DELETE https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks/bfab10fb-cb97-488b-9c63-989c32980b0f \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Before Deleting:**
- • Verify no active calls are using this trunk
- • Document any credentials or routing configurations
- • Check if phone numbers are associated with this trunk
- • Consider exporting trunk configuration for backup
- • Notify users who may be affected by the deletion
);
}

---

# Page: /trunks/credentials

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'use-cases', title: 'Use Cases', level: 2 },
{ id: 'operations', title: 'Available Operations', level: 2 }
];
return (
# Credentials
Manage SIP credentials for username/password authentication on your trunks.
## Introduction
Credentials provide username/password-based authentication for your SIP trunks. Each credential consists of a unique username and password combination that SIP clients can use to authenticate when making or receiving calls through your trunk.
Multiple credentials can be created for a single trunk, allowing different users, devices, or applications to connect with separate authentication details. This provides flexibility in managing access and tracking usage across different endpoints.
**Security Note:** Passwords are write-only and never returned in API responses. Once set, passwords cannot be retrieved - only updated or reset.
**Best Practice:** Use strong passwords (minimum 8 characters) with a mix of uppercase, lowercase, numbers, and special characters. Rotate credentials regularly for enhanced security.
## Use Cases
#### Dynamic IP Environments
Perfect for remote workers, mobile devices, or any scenario where the source IP address changes frequently. Username/password authentication works regardless of network location.
#### Multi-User Access
Create separate credentials for different users or departments, making it easier to track usage and manage access permissions independently.
#### SIP Client Integration
Configure softphones, desk phones, or PBX systems with unique credentials for reliable authentication without IP whitelisting requirements.
#### Combined Authentication
Use credentials alongside IP ACL for maximum security - requiring both valid credentials AND whitelisted IP addresses for authentication.
## Available Operations
1
The Credential Object
Learn about the structure and attributes of credential objects
2
Create Credential
Add new SIP credentials to a trunk with username and password
3
Retrieve All Credentials
List all credentials associated with a trunk with pagination support
4
Update Credential
Modify existing credential properties like password, status, or description
5
Delete Credential
Permanently remove credentials from a trunk
**Quick Start:** Begin by reviewing the credential object structure, then create your first credential to start authenticating SIP clients to your trunk.
);
}

---

# Page: /trunks/credentials/credential-object

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 }
];
return (
# The Credential Object
Complete structure and attributes of a SIP Credential object.
The Credential object represents a set of SIP authentication credentials (username and password) that can be used to authenticate calls on a specific trunk. Multiple credentials can exist for a single trunk, enabling different users, devices, or applications to connect with unique authentication details.
**Password Security:** The `password` field is write-only and will never be returned in API responses. Once created, passwords cannot be retrieved - only updated.
**Username Immutability:** The `username` cannot be changed after credential creation. To use a different username, create a new credential and delete the old one.
## Attributes
## Example
#### Credential Object Response
A typical credential object as returned by the API (note: password is not included):
```
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"trunk_id": "bfab10fb-cb97-488b-9c63-989c32980b0f",
"username": "trunk_user_001",
"enabled": true,
"description": "Primary trunk credential for production",
"created_at": "2025-01-15T10:35:20Z",
"updated_at": "2025-01-15T10:35:20Z"
}
```
**Security Best Practices:**
- • Use strong passwords with at least 12 characters
- • Include uppercase, lowercase, numbers, and special characters
- • Rotate credentials regularly (quarterly recommended)
- • Disable unused credentials immediately rather than deleting them
- • Use descriptive usernames that identify the device or user
);
}

---

# Page: /trunks/credentials/create-credential

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Create Credential
Add new SIP authentication credentials to a trunk.
This API creates a new set of SIP credentials (username and password) for authenticating calls on a specific trunk. The username must be unique within the trunk, and the password must meet minimum security requirements.
**Important:** Save the password securely after creation. The API will never return the password in future responses - it is write-only for security purposes.
**Note:** The username cannot be changed after creation. If you need a different username, create a new credential and delete the old one.
## HTTP Request
POST
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/credentials
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Request Parameters
## Response
Returns the complete credential object including the auto-generated `id` UUID. Note that the password is not included in the response for security reasons.
```
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"username": "trunk_user_002",
"enabled": true,
"description": "Backup credential",
"created_at": "2025-01-22T10:30:00Z",
"updated_at": "2025-01-22T10:30:00Z"
}
```
## Examples
#### cURL - Basic Credential
```
curl -X POST https://api.vobiz.ai/api/v1/account/{Auth_ID}/credentials \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"username": "trunk_user_001",
"password": "SecurePassword123!",
"enabled": true,
"description": "Primary credential"
}'
```
#### cURL - Credential with Strong Password
```
curl -X POST https://api.vobiz.ai/api/v1/account/{Auth_ID}/credentials \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"username": "office_phone_main",
"password": "Vbz!2025$SecureP@ss",
"enabled": true,
"description": "Main office desk phone"
}'
```
**Error Response (409 Conflict):** If the username already exists for this trunk:
```
{
"error": "Username already exists for this trunk",
"code": 409
}
```
**Next Steps:**
- • Save the credential `id` for future operations
- • Store the password securely in your password manager
- • Configure your SIP client with the username and password
- • Test authentication by making a test call
);
}

---

# Page: /trunks/credentials/retrieve-all-credentials

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'query-parameters', title: 'Query Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Retrieve All Credentials
List all SIP credentials associated with a trunk.
This API retrieves a paginated list of all credentials associated with the account. Use this endpoint to audit all authentication credentials, review which usernames are in use, or identify disabled credentials that can be cleaned up.
**Pagination Support:** Results are paginated using limit and offset parameters. The response includes metadata showing the total count, current offset, and limit applied.
## HTTP Request
GET
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/trunks/credentials
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Query Parameters
## Response
Returns a paginated response with metadata and an array of credential objects. Passwords are never included in the response.
```
{
"meta": {
"limit": 20,
"offset": 0,
"total_count": 3
},
"objects": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"username": "trunk_user_001",
"enabled": true,
"description": "Primary trunk credential",
"created_at": "2025-01-15T10:35:20Z",
"updated_at": "2025-01-15T10:35:20Z"
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"username": "trunk_user_002",
"enabled": true,
"description": "Backup credential",
"created_at": "2025-01-16T14:20:30Z",
"updated_at": "2025-01-16T14:20:30Z"
},
{
"id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"username": "trunk_user_003",
"enabled": false,
"description": "Disabled test credential",
"created_at": "2025-01-17T09:15:45Z",
"updated_at": "2025-01-20T16:30:00Z"
}
]
}
```
## Examples
#### cURL - Default Pagination
```
curl -X GET https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks/credentials \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### cURL - Custom Pagination
```
curl -X GET "https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks/credentials?limit=10&offset=0" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Pagination Tips:**
- • Use `total_count` from metadata to calculate total pages
- • Increment offset by limit value for each subsequent page
- • Page 1: offset=0, Page 2: offset=20, Page 3: offset=40 (with limit=20)
- • Empty `objects` array indicates no more results
**Use Case:** This endpoint is ideal for displaying credential management interfaces, auditing which credentials are active, and identifying unused credentials that can be safely removed.
);
}

---

# Page: /trunks/credentials/update-credential

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Update Credential
Modify existing SIP credential properties.
This API updates an existing credential's password, enabled status, or description. Use this endpoint to rotate passwords, enable or disable credentials, or update descriptive information.
**Important Limitation:** The username cannot be changed after credential creation. If you need a different username, you must create a new credential and delete the old one.
**Security Note:** When updating the password, ensure it meets minimum security requirements (8+ characters). The new password will not be returned in the response.
## HTTP Request
PUT
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/credentials/{`{credential_id}`}
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Request Parameters
All parameters are optional. Include only the fields you want to update.
**Note:** The `username` field cannot be updated. It is immutable after credential creation.
## Response
Returns the updated credential object with the new values. The password is not included in the response. Note the `updated_at` timestamp reflects when the change was made.
```
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"username": "trunk_user_001",
"enabled": false,
"description": "Updated credential description",
"created_at": "2025-01-15T10:35:20Z",
"updated_at": "2025-01-22T11:15:45Z"
}
```
## Examples
#### cURL - Update Password
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/credentials/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"password": "UpdatedSecurePassword456!",
"description": "Password rotated on 2025-01-22"
}'
```
#### cURL - Disable Credential
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/credentials/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"enabled": false,
"description": "Temporarily disabled for maintenance"
}'
```
#### cURL - Re-enable Credential
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/credentials/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"enabled": true,
"description": "Re-enabled after maintenance"
}'
```
**Best Practices:**
- • Rotate passwords quarterly or when a device is compromised
- • Use the `enabled` flag to disable credentials temporarily instead of deleting them
- • Update the description when making changes to document the reason
- • Notify affected users before changing passwords to prevent service disruption
**Error Response (404):** If the credential_id doesn't exist or doesn't belong to the specified trunk, you'll receive a 404 Not Found error.
);
}

---

# Page: /trunks/credentials/delete-credential

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Delete Credential
Permanently remove SIP credentials from a trunk.
This API permanently deletes a credential from a trunk. Once deleted, the credential can no longer be used for SIP authentication, and any devices or applications using this credential will be unable to connect. This action cannot be undone.
**Warning:** Deleting a credential will:
- • Immediately prevent authentication using this username and password
- • Disconnect any active calls using this credential
- • Block any devices configured with this credential from making new calls
- • Permanently remove the credential - this cannot be undone
**Alternative:** Consider disabling the credential instead (set `enabled: false`) to temporarily prevent authentication while preserving the credential for future use or audit purposes.
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/credentials/{`{credential_id}`}
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Response
Returns HTTP 204 No Content on successful deletion. No response body is returned.
```
curl -X DELETE https://api.vobiz.ai/api/v1/account/{Auth_ID}/credentials/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Before Deleting:**
- • Verify no active calls are using this credential
- • Document the credential details (username, description) for records
- • Check if any devices or applications are configured with this credential
- • Notify affected users who may be using this credential
- • Consider disabling instead of deleting to preserve audit trail
- • Ensure you have alternative credentials configured for the trunk
**Common Use Cases:**
- • Removing credentials for decommissioned devices
- • Cleaning up test credentials after development
- • Deleting compromised credentials after creating replacements
- • Removing access for users who no longer need it
**Recovery:** If you accidentally delete a credential, you cannot recover it. You'll need to create a new credential with a new username and password, then reconfigure all affected devices.
);
}

---

# Page: /trunks/ip-acl

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'use-cases', title: 'Use Cases', level: 2 },
{ id: 'ip-acl-vs-credentials', title: 'IP ACL vs Credentials', level: 2 },
{ id: 'operations', title: 'Available Operations', level: 2 }
];
return (
# IP Access Control Lists
Manage IP-based authentication for your SIP trunks using IP whitelisting.
## Introduction
IP Access Control Lists (IP ACLs) provide IP-based authentication for your SIP trunks. By whitelisting specific IPv4 addresses, you can allow calls from trusted sources without requiring username/password authentication. This is ideal for scenarios with static IP addresses such as PBX systems, SIP gateways, or carrier connections.
Multiple IP addresses can be whitelisted for a single trunk, allowing connections from different locations or devices. Each IP ACL entry can be individually enabled or disabled, providing flexible control over which sources can authenticate to your trunk.
**IPv4 Only:** Currently, IP ACL only supports IPv4 addresses. IPv6 support is not available at this time.
**Static IPs Required:** IP-based authentication works best with static IP addresses. If your IP address changes frequently, consider using credential-based authentication instead.
## Use Cases
#### Office PBX Systems
Perfect for on-premises PBX systems with static public IP addresses. Simplifies configuration by eliminating the need to manage credentials on the PBX.
#### SIP Gateway Integration
Ideal for SIP gateways and Session Border Controllers (SBCs) that operate from known, fixed IP addresses. Provides faster authentication without credential exchange.
#### Carrier Interconnections
Commonly used for trunk connections with telecom carriers who provide calls from specific IP addresses. Standard practice in carrier-to-carrier peering.
#### Data Center Deployments
Excellent for cloud or data center deployments where your infrastructure has dedicated static IPs. Reduces authentication overhead and improves performance.
## IP ACL vs Credentials
Feature
IP ACL
Credentials
Best For
Static IP addresses
Dynamic IP addresses
Setup Complexity
Simple (no client config)
Moderate (configure username/password)
Security Level
Good (IP-based)
Better (cryptographic)
Performance
Faster (no auth exchange)
Slightly slower (auth required)
NAT Compatibility
Limited (public IP only)
Excellent (works anywhere)
Combined Use
Both can be used together for maximum security
**Maximum Security:** For production environments, consider using both IP ACL and credentials together. This requires authentication from both a whitelisted IP address AND valid credentials, providing defense in depth.
## Available Operations
1
The IP ACL Object
Learn about the structure and attributes of IP ACL objects
2
Create IP ACL
Whitelist a new IPv4 address for trunk authentication
3
Retrieve All IP ACLs
List all IP ACL entries for a trunk with pagination support
4
Update IP ACL
Modify existing IP ACL properties like IP address, status, or description
5
Delete IP ACL
Permanently remove an IP address from the whitelist
**NAT Considerations:** If your SIP client is behind NAT, the source IP address will be the public IP of your router/firewall, not the private IP of the device.
You can find your public IP by visiting services like `https://api.ipify.org`
);
}

---

# Page: /trunks/ip-acl/ip-acl-object

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 }
];
return (
# The IP ACL Object
Complete structure and attributes of an IP Access Control List object.
The IP ACL object represents a whitelisted IPv4 address that can authenticate to a specific trunk without requiring credentials. Each IP ACL entry is associated with a trunk and contains the IP address along with optional metadata like description and enabled status.
**IPv4 Only:** The `ip_address` field only accepts IPv4 addresses in standard dotted-decimal notation (e.g., 192.168.1.1). IPv6 addresses are not currently supported.
**Public IPs:** Ensure you whitelist the public IP address, not private/internal IPs. For devices behind NAT, use the router's public IP address.
## Attributes
## Example
#### IP ACL Object Response
A typical IP ACL object as returned by the API:
```
{
"id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
"trunk_id": "bfab10fb-cb97-488b-9c63-989c32980b0f",
"ip_address": "203.0.113.50",
"description": "Office static IP",
"enabled": true,
"created_at": "2025-01-15T10:40:15Z",
"updated_at": "2025-01-15T10:40:15Z"
}
```
**Best Practices:**
- • Only whitelist IP addresses you control and trust
- • Use descriptive descriptions to identify each IP's purpose
- • Regularly audit your IP ACL list and remove unused entries
- • For dynamic IPs, consider using credential authentication instead
- • Test connectivity after adding new IP addresses
- • Disable rather than delete entries when temporarily blocking access
**Finding Your Public IP:** If you're unsure of your public IP address, you can check it by running `curl https://api.ipify.org` from your command line or visiting the URL in your browser.
);
}

---

# Page: /trunks/ip-acl/create-ip-acl

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Create IP ACL
Whitelist a new IPv4 address for IP-based trunk authentication.
This API creates a new IP ACL entry to whitelist an IPv4 address for authentication on the account. Once added, calls originating from the whitelisted IP address will be allowed without requiring credential authentication (unless both authentication methods are required).
**Public IP Required:** Make sure to whitelist your public IP address, not a private/internal IP. If you're behind NAT, use your router's public IP address.
**IPv4 Only:** Only IPv4 addresses are supported. IPv6 addresses will be rejected with a validation error.
## HTTP Request
POST
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/ip-acl
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Request Parameters
## Response
Returns the complete IP ACL object including the auto-generated `id` UUID and timestamps.
```
{
"id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
"ip_address": "192.168.1.100",
"description": "Office IP address",
"enabled": true,
"created_at": "2025-01-22T11:20:30Z",
"updated_at": "2025-01-22T11:20:30Z"
}
```
## Examples
#### cURL - Basic IP ACL
```
curl -X POST https://api.vobiz.ai/api/v1/account/{Auth_ID}/ip-acl \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"ip_address": "203.0.113.50",
"description": "Office static IP",
"enabled": true
}'
```
#### cURL - PBX Server IP
```
curl -X POST https://api.vobiz.ai/api/v1/account/{Auth_ID}/ip-acl \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"ip_address": "198.51.100.42",
"description": "FreePBX server in data center",
"enabled": true
}'
```
**Error Response (400 Bad Request):** If the IP address format is invalid:
```
{
"error": "Invalid IP address format",
"code": 400
}
```
**Next Steps:**
- • Save the IP ACL `id` for future operations
- • Verify the IP address is correct before testing
- • Test connectivity by making a call from the whitelisted IP
- • Monitor authentication logs to confirm IP-based auth is working
**NAT Tip:** If you're behind NAT or a firewall, determine your public IP with: `curl https://api.ipify.org`
);
}

---

# Page: /trunks/ip-acl/retrieve-all-ip-acls

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'query-parameters', title: 'Query Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Retrieve All IP ACLs
List all IP ACL entries for a trunk with pagination support.
This API retrieves a paginated list of all IP ACL entries associated with the account. Use this endpoint to view all whitelisted IP addresses, audit your IP access configuration, and manage multiple IP ACL entries.
**Security Audit:** Regularly review this list to ensure only authorized IP addresses are whitelisted. Remove any entries that are no longer needed.
## HTTP Request
GET
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/trunks/ip-acl
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Query Parameters
## Response
Returns a paginated list of IP ACL objects with metadata about pagination state.
```
{
"meta": {
"limit": 20,
"offset": 0,
"total_count": 5
},
"objects": [
{
"id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
"ip_address": "203.0.113.50",
"description": "Office static IP",
"enabled": true,
"created_at": "2025-01-15T10:40:15Z",
"updated_at": "2025-01-15T10:40:15Z"
},
{
"id": "d2e3f4a5-b6c7-8901-def1-234567890abc",
"ip_address": "198.51.100.42",
"description": "PBX server in data center",
"enabled": true,
"created_at": "2025-01-16T09:20:30Z",
"updated_at": "2025-01-16T09:20:30Z"
},
{
"id": "e3f4a5b6-c7d8-9012-ef12-34567890abcd",
"ip_address": "192.0.2.100",
"description": "Backup office IP",
"enabled": false,
"created_at": "2025-01-17T14:15:45Z",
"updated_at": "2025-01-20T11:30:00Z"
}
]
}
```
## Examples
#### cURL - Default Pagination
```
curl -X GET "https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks/ip-acl" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### cURL - Custom Pagination
```
curl -X GET "https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks/ip-acl?limit=50&offset=0" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Pagination Tip:** Use `total_count` from the meta object to calculate total pages. For page 2 with limit 20, use offset=20.
**Monitoring:** Review the `enabled` field for each entry. Disabled entries appear in the list but won't allow authentication. Check `updated_at` to see when entries were last modified.
);
}

---

# Page: /trunks/ip-acl/update-ip-acl

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Update IP ACL
Modify an existing IP ACL entry's properties.
This API updates an existing IP ACL entry. You can change the whitelisted IP address, modify the description, or enable/disable the entry. All fields are optional - only include the fields you want to update.
**Partial Updates:** You can update any combination of fields. Fields not included in the request will retain their current values.
**Disable vs Delete:** To temporarily block an IP without losing the configuration, set `enabled: false` instead of deleting the entry.
## HTTP Request
PUT
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/ip-acl/{`{ip_acl_id}`}
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Request Parameters
All parameters are optional. Only include the fields you want to update.
## Response
Returns the complete updated IP ACL object with the new values and an updated `updated_at` timestamp.
```
{
"id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
"ip_address": "192.168.1.200",
"description": "Updated office IP address",
"enabled": false,
"created_at": "2025-01-15T10:40:15Z",
"updated_at": "2025-01-22T11:45:20Z"
}
```
## Examples
#### cURL - Update IP Address
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/ip-acl/c1d2e3f4-a5b6-7890-cdef-1234567890ab \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"ip_address": "192.168.1.200",
"description": "Updated office IP after ISP change"
}'
```
#### cURL - Disable IP ACL Entry
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/ip-acl/c1d2e3f4-a5b6-7890-cdef-1234567890ab \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"enabled": false
}'
```
#### cURL - Update Description Only
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/ip-acl/c1d2e3f4-a5b6-7890-cdef-1234567890ab \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"description": "Main office - Building A"
}'
```
**IP Address Changes:** If you update the IP address, existing authenticated connections may be disconnected. Plan IP changes during maintenance windows.
**Error Response (400 Bad Request):** If the new IP address format is invalid:
```
{
"error": "Invalid IP address format",
"code": 400
}
```
**Best Practice:** When changing IP addresses, add the new IP first, test connectivity, then disable or delete the old IP entry to avoid service interruption.
);
}

---

# Page: /trunks/ip-acl/delete-ip-acl

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Delete IP ACL
Permanently remove an IP address from the trunk whitelist.
This API permanently deletes an IP ACL entry from a trunk. Once deleted, the IP address will no longer be whitelisted for authentication, and calls from this IP will be rejected unless other authentication methods (like credentials) are configured and valid.
**Warning:** This action is permanent and cannot be undone. Active connections from this IP address may be immediately disconnected.
**Alternative:** Consider disabling the IP ACL entry instead of deleting it by setting `enabled: false`. This preserves the configuration for future use.
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/ip-acl/{`{ip_acl_id}`}
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Response
Returns HTTP 204 No Content on successful deletion. No response body is returned.
```
No Content
```
## Examples
#### cURL - Delete IP ACL
```
curl -X DELETE https://api.vobiz.ai/api/v1/account/{Auth_ID}/ip-acl/c1d2e3f4-a5b6-7890-cdef-1234567890ab \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Error Response (404 Not Found):** If the IP ACL ID doesn't exist or was already deleted:
```
{
"error": "IP ACL not found",
"code": 404
}
```
**Before Deleting:**
- • Verify you have the correct IP ACL ID
- • Ensure you have alternative authentication methods configured (if needed)
- • Check if there are active connections from this IP
- • Consider temporarily disabling instead of deleting
**After Deletion:**
- • The IP address is immediately removed from the whitelist
- • New authentication attempts from this IP will fail
- • Active calls may be terminated depending on trunk configuration
- • The IP ACL entry cannot be recovered - create a new one if needed
**Alternative - Disable Instead:** To temporarily block an IP without losing the configuration:
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/ip-acl/IP_ACL_ID \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{"enabled": false}'
```
);
}

---

# Page: /trunks/origination-uri

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'use-cases', title: 'Use Cases', level: 2 },
{ id: 'operations', title: 'Available Operations', level: 2 }
];
return (
# Origination URIs
Configure outbound SIP routing destinations for your trunk calls.
## Introduction
Origination URIs define the SIP endpoints where outbound calls from your trunk will be routed. Each URI represents a destination carrier, SIP provider, PBX system, or other SIP-capable endpoint that will receive your outbound traffic.
You can configure multiple origination URIs per trunk to implement load balancing and failover strategies. The system uses priority and weight values to intelligently distribute traffic across your configured destinations, ensuring high availability and optimal resource utilization.
**Priority:** Lower numbers indicate higher priority. URIs with priority 1 are tried first, then priority 2 as failover, and so on.
**Weight:** Used for load balancing among URIs with the same priority. Higher weight values receive proportionally more traffic. For example, a URI with weight 20 receives twice the traffic of one with weight 10.
## Use Cases
#### Carrier Interconnection
Route outbound calls to your upstream carrier or SIP provider. Configure primary and backup carriers with different priorities to ensure uninterrupted service if your primary carrier experiences issues.
#### PBX Integration
Connect your trunk to an on-premises or cloud PBX system. Route calls to your FreeSWITCH, Asterisk, or other SIP-capable PBX for call processing, IVR, call routing, and other telephony features.
#### Load Balancing
Distribute call traffic across multiple SIP servers using weight-based load balancing. Configure multiple URIs with the same priority but different weights to control traffic distribution ratios.
#### Geographic Redundancy
Configure origination URIs pointing to SIP servers in different geographic regions. If one region becomes unavailable, calls automatically fail over to servers in other regions based on priority settings.
## Available Operations
1
The Origination URI Object
Learn about the structure and attributes of origination URI objects
2
Create Origination URI
Add new SIP destination endpoints for outbound call routing
3
Retrieve All Origination URIs
List all origination URIs associated with a trunk with pagination support
4
Update Origination URI
Modify URI, priority, weight, or status of existing origination URIs
5
Delete Origination URI
Permanently remove an origination URI from a trunk
**Quick Start:** Begin by reviewing the origination URI object structure, then create your first URI to start routing outbound calls. Configure multiple URIs with different priorities for failover.
);
}

---

# Page: /trunks/origination-uri/origination-uri-object

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 }
];
return (
# The Origination URI Object
Complete structure and attributes of an Origination URI object.
The Origination URI object represents a SIP endpoint destination for outbound calls. Each URI specifies where your trunk should route outbound traffic, along with priority and weight settings that control failover behavior and load distribution.
**SIP URI Format:** Origination URIs must follow the standard SIP URI format: `sip:user@host:port` or `sip:host:port`
**Examples:** `sip:provider@sip.example.com:5060`, `sip:192.168.1.100:5060`
## Attributes
## Example
#### Origination URI Object Response
A typical origination URI object as returned by the API:
```
{
"id": "e1f2a3b4-c5d6-7890-efab-567890123456",
"trunk_id": "bfab10fb-cb97-488b-9c63-989c32980b0f",
"uri": "sip:provider@sip.example.com:5060",
"priority": 1,
"weight": 10,
"enabled": true,
"created_at": "2025-01-15T10:45:30Z",
"updated_at": "2025-01-15T10:45:30Z"
}
```
**Priority-Based Routing:** The system tries URIs in order of priority (lowest number first). If all priority 1 URIs fail, it attempts priority 2, and so on.
**Weight-Based Load Balancing:** Among URIs with the same priority, traffic is distributed proportionally based on weight. A URI with weight 20 receives twice the traffic of one with weight 10.
**Example:** With two URIs at priority 1 (weights 10 and 20), the first receives ~33% of traffic and the second receives ~67%.
);
}

---

# Page: /trunks/origination-uri/create-origination-uri

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Create Origination URI
Add a new SIP destination endpoint for outbound call routing.
This API creates a new origination URI (SIP destination) for routing outbound calls from your trunk. The URI must be a valid SIP endpoint in the format `sip:user@host:port` or `sip:host:port`.
**Valid SIP URI Formats:**
- • `sip:provider@sip.example.com:5060` - Domain with user
- • `sip:192.168.1.100:5060` - IP address
- • `sip:trunk@sip.carrier.net:5061` - Custom port
**Invalid Formats:**
- • `http://sip.example.com` - Wrong protocol
- • `provider@sip.example.com:5060` - Missing sip: prefix
- • `sip:example.com` - Missing port number
## HTTP Request
POST
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/origination-uris
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Request Parameters
## Response
Returns the complete origination URI object including the auto-generated `id` UUID and timestamps.
```
{
"id": "e1f2a3b4-c5d6-7890-efab-567890123456",
"uri": "sip:provider@sip.example.com:5060",
"priority": 1,
"weight": 10,
"enabled": true,
"created_at": "2025-01-22T12:00:15Z",
"updated_at": "2025-01-22T12:00:15Z"
}
```
## Examples
#### cURL - Primary Origination URI
```
curl -X POST https://api.vobiz.ai/api/v1/account/{Auth_ID}/origination-uris \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"uri": "sip:provider@sip.example.com:5060",
"priority": 1,
"weight": 10,
"enabled": true
}'
```
#### cURL - Failover URI with Lower Priority
```
curl -X POST https://api.vobiz.ai/api/v1/account/{Auth_ID}/origination-uris \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"uri": "sip:backup@sip-backup.example.com:5060",
"priority": 2,
"weight": 10,
"enabled": true
}'
```
#### cURL - Load Balancing Configuration
Create two URIs with the same priority but different weights for 70/30 traffic split:
```
curl -X POST https://api.vobiz.ai/api/v1/account/{Auth_ID}/origination-uris \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"uri": "sip:server1@sip.example.com:5060",
"priority": 1,
"weight": 70
}'
```
```
curl -X POST https://api.vobiz.ai/api/v1/account/{Auth_ID}/origination-uris \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"uri": "sip:server2@sip.example.com:5060",
"priority": 1,
"weight": 30
}'
```
**Error Response (400 Bad Request):** If SIP URI format is invalid:
```
{
"error": "Invalid SIP URI format. Expected: sip:user@host:port",
"code": 400
}
```
**Best Practices:**
- • Configure at least 2 origination URIs for redundancy (one primary, one failover)
- • Use priority 1 for primary destinations, priority 2 for backup/failover
- • Adjust weights to distribute load across multiple carriers or servers
- • Test connectivity to each URI before enabling in production
);
}

---

# Page: /trunks/origination-uri/retrieve-all-origination-uris

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'query-parameters', title: 'Query Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Retrieve All Origination URIs
List all origination URIs associated with a trunk.
This API retrieves all origination URIs configured for a specific trunk. The response includes routing configuration such as priority, weight, and enabled status for each URI. Use pagination parameters to control the number of results returned.
**Use Case:** List all routing destinations to audit your trunk's outbound call routing configuration, verify failover setup, or analyze load balancing distribution across multiple carriers.
## HTTP Request
GET
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/trunks/origination-uris
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Query Parameters
## Response
Returns a paginated list of origination URI objects with metadata about the result set.
```
{
"meta": {
"limit": 20,
"offset": 0,
"total_count": 3
},
"objects": [
{
"id": "e1f2a3b4-c5d6-7890-efab-567890123456",
"uri": "sip:provider@sip.example.com:5060",
"priority": 1,
"weight": 10,
"enabled": true,
"created_at": "2025-01-15T10:45:30Z",
"updated_at": "2025-01-15T10:45:30Z"
},
{
"id": "f2g3h4i5-j6k7-8901-lmno-678901234567",
"uri": "sip:backup@sip-backup.example.com:5060",
"priority": 2,
"weight": 10,
"enabled": true,
"created_at": "2025-01-15T11:00:00Z",
"updated_at": "2025-01-15T11:00:00Z"
},
{
"id": "g3h4i5j6-k7l8-9012-mnop-789012345678",
"uri": "sip:secondary@sip.example.com:5060",
"priority": 1,
"weight": 20,
"enabled": true,
"created_at": "2025-01-15T11:15:00Z",
"updated_at": "2025-01-15T11:15:00Z"
}
]
}
```
**Example Routing Logic:**
- • Priority 1 URIs (first and third) handle primary traffic
- • Among priority 1, traffic is split 33% to first URI (weight 10) and 67% to third URI (weight 20)
- • Priority 2 URI (second) serves as failover if all priority 1 URIs fail
## Examples
#### cURL - List All URIs
```
curl -X GET https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks/origination-uris \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
#### cURL - Paginated Results
```
curl -X GET "https://api.vobiz.ai/api/v1/account/{Auth_ID}/trunks/origination-uris?limit=10&offset=0" \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Pagination:**
- • Use `limit` to control page size
- • Use `offset` to skip to a specific page
- • Check `total_count` in meta to determine total URIs
- • Calculate total pages: `Math.ceil(total_count / limit)`
);
}

---

# Page: /trunks/origination-uri/update-origination-uri

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'request-parameters', title: 'Request Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Update Origination URI
Modify an existing origination URI's configuration.
This API updates an existing origination URI. You can modify the SIP destination, adjust priority and weight for routing optimization, or enable/disable the URI without deleting it. All fields are optional - only include the fields you want to change.
**Common Use Cases:**
- • Change URI priority to implement failover strategies or promote a backup URI to primary
- • Adjust weights to rebalance traffic distribution across multiple carriers
- • Update the SIP destination when switching carriers or changing server addresses
- • Temporarily disable a URI (enabled: false) without deleting it for maintenance windows
## HTTP Request
PUT
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/origination-uris/{`{uri_id}`}
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Request Parameters
All parameters are optional. Only include fields you want to update.
## Response
Returns the complete updated origination URI object with the new values and an updated timestamp.
```
{
"id": "e1f2a3b4-c5d6-7890-efab-567890123456",
"uri": "sip:updated@sip.example.com:5060",
"priority": 2,
"weight": 20,
"enabled": false,
"created_at": "2025-01-15T10:45:30Z",
"updated_at": "2025-01-22T12:30:45Z"
}
```
## Examples
#### cURL - Change Priority for Failover
Promote a backup URI (priority 2) to primary (priority 1):
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/origination-uris/e1f2a3b4-c5d6-7890-efab-567890123456 \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"priority": 1
}'
```
#### cURL - Adjust Load Balancing Weight
Increase weight to shift more traffic to this URI:
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/origination-uris/e1f2a3b4-c5d6-7890-efab-567890123456 \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"weight": 50
}'
```
#### cURL - Update SIP Destination
Change the URI to point to a different carrier or server:
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/origination-uris/e1f2a3b4-c5d6-7890-efab-567890123456 \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"uri": "sip:newcarrier@sip.newprovider.com:5060"
}'
```
#### cURL - Temporarily Disable URI
Disable URI for maintenance without deleting it:
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/origination-uris/e1f2a3b4-c5d6-7890-efab-567890123456 \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"enabled": false
}'
```
#### cURL - Multiple Updates
Update multiple fields in a single request:
```
curl -X PUT https://api.vobiz.ai/api/v1/account/{Auth_ID}/origination-uris/e1f2a3b4-c5d6-7890-efab-567890123456 \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"uri": "sip:updated@sip.example.com:5060",
"priority": 1,
"weight": 30,
"enabled": true
}'
```
**Failover Strategy Example:**
- • If primary carrier fails, update priority from 2 to 1 to promote backup to primary
- • After carrier maintenance, restore original priority settings
- • Use enabled: false during planned maintenance instead of changing priorities
- • Test connectivity before re-enabling URIs after maintenance
);
}

---

# Page: /trunks/origination-uri/delete-origination-uri

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Delete Origination URI
Permanently remove an origination URI from a trunk.
This API permanently deletes an origination URI from your trunk. Once deleted, the trunk will no longer route outbound calls to this destination. The operation cannot be undone - deleted URIs must be recreated if needed again.
**Warning:** Deleting an origination URI is permanent and cannot be reversed. Ensure you have at least one active URI remaining for outbound calls to continue functioning.
**Important:** If you delete all origination URIs, your trunk will not be able to route any outbound calls. Always maintain at least one active URI for production trunks.
**Alternative:** Instead of deleting, consider setting `enabled: false` to temporarily disable the URI without losing the configuration.
This allows you to re-enable the URI later without needing to reconfigure the SIP destination, priority, and weight.
## HTTP Request
DELETE
https://api.vobiz.ai/api/v1/account/{`{account_id}`}/origination-uris/{`{uri_id}`}
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., {'{Auth_ID}'})
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Response
Returns HTTP 204 No Content on successful deletion. No response body is returned.
```
No Content
```
## Examples
#### cURL - Delete Origination URI
```
curl -X DELETE https://api.vobiz.ai/api/v1/account/{Auth_ID}/origination-uris/e1f2a3b4-c5d6-7890-efab-567890123456 \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
```
**Error Response (404 Not Found):** If the origination URI does not exist:
```
{
"error": "Origination URI not found",
"code": 404
}
```
**Before Deleting:**
- • List all origination URIs to verify you're deleting the correct one
- • Ensure at least one other active URI exists for outbound call routing
- • Consider the impact on failover and load balancing configuration
- • Save URI configuration details if you might need to recreate it later
**Safe Deletion Workflow:**
- First, set `enabled: false` on the URI to disable it
- Monitor outbound calls to ensure remaining URIs handle traffic correctly
- Wait for a testing period (e.g., 24 hours) to confirm no issues
- If no problems occur, proceed with permanent deletion
- If issues arise, re-enable the URI before it's deleted
**Production Best Practices:**
- • Never delete the last remaining active origination URI on a production trunk
- • Always maintain at least 2 URIs (one primary, one backup) for redundancy
- • Document the reason for deletion and the URI configuration in your change log
- • Plan deletions during maintenance windows to minimize potential impact
);
}

---

# Page: /xml/overview

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'how-it-works', title: 'How XML Works', level: 2 },
{ id: 'xml-elements', title: 'XML Elements', level: 2 },
{ id: 'response-element', title: 'Response Element', level: 3 },
{ id: 'verb-elements', title: 'Verb Elements', level: 3 },
{ id: 'noun-elements', title: 'Noun Elements', level: 3 },
{ id: 'getting-started', title: 'Getting Started', level: 2 },
{ id: 'best-practices', title: 'Best Practices', level: 2 }
];
return (
{/* Header Section */}
# XML Reference
Control call flow and behavior using XML instructions. Build interactive voice response (IVR) systems, handle call routing, play media, record calls, and create dynamic telephony applications using Vobiz XML.
### What is Vobiz XML?
Vobiz XML is a markup language that instructs the Vobiz platform on how to handle voice calls. When your application receives a webhook for an incoming or outgoing call, you respond with XML instructions that tell Vobiz what to do with the call - play audio, record the conversation, dial another number, collect user input, and more.
- **Declarative syntax:** Simple, readable XML structure for call control
- **Event-driven:** Respond to call events with XML instructions via webhooks
- **Composable:** Combine multiple elements to create complex call flows
- **Dynamic:** Generate XML programmatically based on business logic
{/* How It Works */}
## How XML Works
### Request-Response Flow
1
#### Call Event Occurs
An incoming call arrives, or an outbound call connects. Vobiz needs instructions on what to do next.
2
#### Webhook Request
Vobiz sends an HTTP POST request to your configured Answer URL or Action URL with call details (caller ID, call ID, DTMF digits, recording URL, etc.).
3
#### Your Application Responds with XML
Your server processes the request (query database, check business rules, etc.) and returns XML instructions telling Vobiz what to do with the call.
4
#### Vobiz Executes XML
Vobiz parses your XML and executes the instructions in order - playing audio, collecting input, dialing numbers, recording, etc.
5
#### Loop Continues
If your XML includes action URLs (e.g., after recording or input collection), Vobiz requests new XML from those URLs and the cycle continues.
```
Welcome to Vobiz! Press 1 for sales, 2 for support, or 0 for operator.
We did not receive your input.
```
{/* XML Elements */}
## XML Elements
Vobiz XML consists of three types of elements: the root `Response` element, verb elements that perform actions, and noun elements that modify verbs.
{/* Response Element */}
### Response Element
`<Response>`
→
The root element that wraps all other XML elements. Every XML document must have exactly one `Response` element.
{/* Verb Elements */}
### Verb Elements (Actions)
Verb elements instruct Vobiz to perform specific actions during a call. They are the primary building blocks of your call flow.
{[
{ name: 'Speak', href: '/xml/speak', desc: 'Convert text to speech and play it to the caller' },
{ name: 'Play', href: '/xml/play', desc: 'Play an audio file (MP3, WAV) from a URL' },
{ name: 'Dial', href: '/xml/dial', desc: 'Dial a phone number or SIP address' },
{ name: 'Record', href: '/xml/record', desc: 'Record the call audio' },
{ name: 'Gather', href: '/xml/gather', desc: 'Collect speech or DTMF input' },
{ name: 'Hangup', href: '/xml/hangup', desc: 'Terminate the call' },
{ name: 'Redirect', href: '/xml/redirect', desc: 'Transfer control to a different URL' },
{ name: 'Wait', href: '/xml/wait', desc: 'Pause execution for a specified duration' },
{ name: 'Conference', href: '/xml/conference', desc: 'Connect caller to a conference room' },
{ name: 'DTMF', href: '/xml/dtmf', desc: 'Send DTMF tones during a call' },
{ name: 'PreAnswer', href: '/xml/preanswer', desc: 'Answer call in early media mode' },
{ name: 'Stream', href: '/xml/stream', desc: 'Stream call audio to external service' },
{ name: 'MultiPartyCall', href: '/xml/multipartycall', desc: 'Manage multi-party call sessions' },
].map((element) => (
<{element.name}>
→
{element.desc}
))}
{/* Noun Elements */}
### Noun Elements (Modifiers)
Noun elements are nested inside verb elements to modify their behavior. They provide additional context and options for the parent verb.
`<Request>`
→
Nested within certain elements to make HTTP requests with custom parameters
{/* Getting Started */}
## Getting Started
### Basic Example
Here's a simple example that demonstrates answering a call, playing a message, and hanging up:
```
Hello! Welcome to Vobiz telephony platform.
```
### Interactive IVR Example
A more advanced example showing user input collection and conditional routing:
```
Press 1 for account information.
Press 2 to speak with a representative.
Press 9 to repeat this menu.
We didn't receive any input. Goodbye!
```
### Call Recording Example
Record a voicemail message with a beep before recording:
```
Please leave a message after the beep.
https://yourcdn.com/beep.mp3
Thank you for your message. Goodbye!
```
{/* Best Practices */}
## Best Practices
### Keep It Simple  Start with basic XML and gradually add complexity. Test each element thoroughly before combining multiple actions.
### Set Timeouts  Always set appropriate timeouts for Gather to handle non-responsive callers gracefully.
### Handle Errors  Provide fallback actions when input collection fails or URLs are unreachable. Always have a path to Hangup or Redirect.
### Log Everything  Log all webhook requests and your XML responses for debugging. Use unique identifiers to trace call flows through your system.
### User-Friendly Prompts  Write clear, concise voice prompts. Avoid jargon and provide obvious choices. Repeat options when users don't respond.
### Valid XML  Ensure your XML is well-formed with proper opening/closing tags, escaped special characters (&, <, >, "), and UTF-8 encoding.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/overview/how-it-works

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'request-response', title: 'Request-Response Flow', level: 2 },
{ id: 'webhook-lifecycle', title: 'Webhook Lifecycle', level: 2 },
{ id: 'example-flow', title: 'Example Flow', level: 2 },
];
return (
{/* Header Section */}
# How XML Works
Understand the request-response cycle between Vobiz and your application. Learn how XML instructions control call flow through webhooks and dynamic responses.
### Event-Driven Architecture
Vobiz XML operates on an event-driven model. When call events occur (incoming call, DTMF pressed, recording complete), Vobiz sends HTTP requests to your configured URLs and executes the XML you return. This allows you to build dynamic, data-driven call flows.
{/* Request-Response Flow */}
## Request-Response Flow
### The Basic Cycle
1
#### Call Event Triggers
An incoming call arrives, an outbound call connects, a user presses a DTMF key, a recording finishes, or any other call event occurs.
2
#### Vobiz Sends Webhook
Vobiz makes an HTTP POST (or GET) request to your Answer URL or Action URL with call details: CallUUID, From, To, Direction, DTMF digits, RecordingURL, etc.
3
#### Your Server Generates XML
Your application processes the webhook data (lookup customer in database, check business rules, etc.) and returns XML instructions in the HTTP response body.
4
#### Vobiz Executes XML
Vobiz parses your XML and executes each element in order: plays audio, collects input, dials numbers, records audio, etc.
5
#### Cycle Repeats
If your XML includes action URLs (on Gather, Record, Dial, etc.), Vobiz requests new XML from those URLs and the cycle continues until the call ends or a Hangup element is reached.
{/* Webhook Lifecycle */}
## Webhook Lifecycle
### Answer URL (Inbound Calls)
When an incoming call arrives at your Vobiz phone number, Vobiz requests XML from the Answer URL configured in your Application settings.
POST https://yourapp.com/answer CallUUID=abc123&From=+14155551234&To=+14155559999&Direction=inbound
### Action URLs (Subsequent Events)
XML elements like Gather, Record, and Dial can specify action URLs. After the action completes, Vobiz requests new XML from that URL with event-specific parameters.
POST https://yourapp.com/menu-choice CallUUID=abc123&Digits=1&From=+14155551234
### Hangup URL (Call End)
When the call ends (hangup, timeout, network issue), Vobiz sends a final webhook to your Hangup URL with call duration, end reason, and other metadata. This is for logging/billing—no XML is expected.
POST https://yourapp.com/hangup CallUUID=abc123&Duration=125&HangupCause=NORMAL_CLEARING
{/* Example Flow */}
## Complete Example Flow
### Step 1: Incoming Call (Answer URL)
Customer calls your Vobiz number. Vobiz sends webhook to your Answer URL:
```
POST /answer HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded
CallUUID=xyz789&From=+14155551234&To=+14155559999&Direction=inbound
```
Your server returns XML to present an IVR menu:
```
Press 1 for sales, 2 for support, 0 for operator.
We didn't receive your input. Goodbye!
```
### Step 2: User Presses "1" (Action URL)
Vobiz collects the digit and sends webhook to the action URL:
```
POST /menu-choice HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded
CallUUID=xyz789&Digits=1&From=+14155551234
```
Your server checks the digit, looks up sales queue, returns XML to transfer:
```
Connecting you to sales. Please hold.
+14155555678
Sorry, no one is available. Please call back later.
```
### Step 3: Call Connects or Fails
If the Dial succeeds, the calls are bridged. When one party hangs up, Vobiz sends webhook to the Dial action URL with the result, then to your Hangup URL when the call fully ends.
{/* Key Takeaways */}
## Key Takeaways
### XML is Stateless
Each webhook is independent. Vobiz doesn't maintain call flow state—your application must track the conversation using CallUUID and database lookups.
### Webhooks Must Respond Fast
Your server should return XML within 1-2 seconds. Slow responses cause dead air for callers. Do heavy processing asynchronously and cache data when possible.
### Chain Actions Together
Use action URLs to build multi-step flows: collect input → validate → transfer → record → send notification. Each step is a separate webhook-XML cycle.
### Always Have a Fallback
If input collection times out or a Dial fails, provide fallback XML (retry, leave voicemail, or Hangup gracefully). Never leave calls in an undefined state.
{/* Previous/Next Navigation */}
);
}

---

# Page: /xml/overview/getting-started

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'prerequisites', title: 'Prerequisites', level: 2 },
{ id: 'hello-world', title: 'Hello World Example', level: 2 },
{ id: 'ivr-example', title: 'IVR Menu Example', level: 2 },
{ id: 'testing', title: 'Testing Your XML', level: 2 },
];
return (
# Getting Started with XML
Build your first voice application with Vobiz XML. This guide walks you through setting up webhooks, writing your first XML responses, and testing call flows.
{/* Prerequisites */}
## Prerequisites
### What You'll Need
✓
A Vobiz account with API access
✓
A phone number purchased from Vobiz
✓
A web server that can receive HTTP requests (webhook endpoint)
✓
Basic understanding of HTTP and XML
### Recommended Tools
•
**ngrok** or similar for local development tunneling
•
**Postman** for testing webhooks
•
**Node.js, Python, or PHP** for server-side logic
•
**XML validator** to check syntax
{/* Hello World */}
## Hello World Example
Let's create the simplest possible voice application: answering a call and speaking a greeting.
### Step 1: Create a Webhook Endpoint
Set up a simple HTTP server that returns XML. Here's a Node.js Express example:
```
const express = require('express');
const app = express();
app.post('/answer', (req, res) => {
const xml = \`
Hello! Welcome to Vobiz telephony platform.
\`;
res.type('application/xml');
res.send(xml);
});
app.listen(3000, () => {
console.log('Server running on port 3000');
});
```
### Step 2: Expose Your Server
For local development, use ngrok to create a public URL:
```
ngrok http 3000
```
ngrok will provide a URL like `https://abc123.ngrok.io`
### Step 3: Configure Your Application
In the Vobiz console, configure your Application's Answer URL:
Answer URL: https://abc123.ngrok.io/answer Method: POST
Assign this Application to your Vobiz phone number. When someone calls that number, they'll hear your greeting!
{/* IVR Example */}
## IVR Menu Example
Now let's build an interactive IVR menu that collects user input and routes calls accordingly.
### Answer Endpoint
```
app.post('/answer', (req, res) => {
const xml = \`
Welcome to our support line.
Press 1 for sales, press 2 for technical support,
or press 0 to speak with an operator.
We didn't receive your input. Goodbye!
\`;
res.type('application/xml');
res.send(xml);
});
```
### Menu Choice Handler
```
app.post('/menu-choice', (req, res) => {
const digit = req.body.Digits;
let xml;
switch(digit) {
case '1':
xml = \`
Connecting you to sales.
+14155551111
\`;
break;
case '2':
xml = \`
Connecting you to technical support.
+14155552222
\`;
break;
case '0':
xml = \`
Transferring to operator.
+14155550000
\`;
break;
default:
xml = \`
Invalid selection. Please try again.
https://abc123.ngrok.io/answer
\`;
}
res.type('application/xml');
res.send(xml);
});
```
{/* Testing */}
## Testing Your XML
### Method 1: Real Phone Calls
The most accurate way to test is to call your Vobiz number from a real phone.
- • Test audio quality and timing
- • Verify DTMF input collection
- • Check call transfer functionality
- • Monitor webhook logs in real-time
### Method 2: Webhook Simulation
Use Postman or cURL to simulate Vobiz webhook requests to your endpoint.
```
curl -X POST https://yourapp.com/answer \\
-d "CallUUID=test123" \\
-d "From=+14155551234" \\
-d "To=+14155559999"
```
### Development Tips
- • Log all incoming webhook data to debug call flows
- • Validate your XML syntax before deploying changes
- • Use descriptive Speak messages to understand which code path executed
- • Start simple and add complexity gradually
- • Monitor server response times—keep them under 1 second
);
}

---

# Page: /xml/overview/best-practices

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'performance', title: 'Performance', level: 2 },
{ id: 'reliability', title: 'Reliability', level: 2 },
{ id: 'security', title: 'Security', level: 2 },
{ id: 'user-experience', title: 'User Experience', level: 2 },
];
return (
# XML Best Practices
Build robust, scalable, and user-friendly voice applications with these proven patterns and recommendations for Vobiz XML development.
{/* Performance */}
## Performance Optimization
### Fast Webhook Responses
Return XML within 1-2 seconds. Slow webhooks create dead air and frustrated callers.
```
app.post('/answer', async (req, res) => {
// DON'T: Heavy processing blocks the response
await sendEmail(req.body.From);
await logToDatabase(req.body);
await fetchCustomerHistory(req.body.From);
res.send(xml); // Too slow!
});
```
```
app.post('/answer', (req, res) => {
// DO: Return XML immediately
res.send(xml);
// Process heavy tasks asynchronously
processCallWebhook(req.body).catch(err => log(err));
});
```
### Cache Frequently Used Data
Cache business hours, routing rules, audio URLs, and other static data. Don't query the database on every webhook—use Redis, memcached, or in-memory caching.
### Optimize Audio Files
Use 8kHz mono MP3 files. Serve from a CDN. Higher quality doesn't improve telephony audio but increases latency and bandwidth costs.
{/* Reliability */}
## Reliability & Error Handling
### Always Provide Fallback Paths
Every Gather and Dial should have a fallback for timeouts or failures.
```
Press 1 for sales, 2 for support.
We didn't receive your selection. Transferring to operator.
+14155550000
```
### Validate XML Syntax
Use XML validators in development and automated tests. Malformed XML causes call failures.
- • Ensure all tags are properly closed
- • Escape special characters (&, <, >, ", &apos;)
- • Use UTF-8 encoding declaration
- • Test with real XML parsers, not string validation
### Handle Network Failures Gracefully
If Vobiz can't reach your webhook URL (timeout, DNS failure, SSL error), the call will drop. Use monitoring tools, health checks, and load balancers to ensure high availability.
### Log Everything
Log all incoming webhooks, generated XML, and errors. Use CallUUID to trace call flows.
```
app.post('/answer', (req, res) => {
const callId = req.body.CallUUID;
logger.info('Incoming call', {
callId,
from: req.body.From,
to: req.body.To
});
const xml = generateXML(req.body);
logger.info('Returning XML', { callId, xml });
res.send(xml);
});
```
{/* Security */}
## Security
### Validate Webhook Signatures
Verify that webhook requests actually come from Vobiz by checking signatures or IP whitelist. This prevents spoofed requests.
### Use HTTPS
All webhook URLs must use HTTPS. HTTP webhooks expose call data and may be blocked.
### Sanitize User Input
Don't trust DTMF digits, caller IDs, or other webhook data. Validate and sanitize before using in database queries or business logic.
```
app.post('/menu', (req, res) => {
const digit = req.body.Digits;
// Validate input is a single digit
if (!/^[0-9]$/.test(digit)) {
return res.send(errorXML);
}
// Safe to use now
routeToQueue(digit);
});
```
### Protect Sensitive Data
Never speak credit card numbers, passwords, or SSNs in TTS. Don't log PII without encryption. Use secure storage for call recordings containing sensitive information.
{/* User Experience */}
## User Experience
### Keep Prompts Concise
Callers lose attention after 15-20 seconds. Break long messages into chunks.
```
Welcome to ABC Company, provider of enterprise software solutions
since 1995. We offer 24/7 support, training, consulting, and managed
services. For sales press 1, for support press 2, for billing press 3...
```
```
Welcome to ABC Company. Press 1 for sales, 2 for support, or 0 for operator.
```
### Provide Clear Instructions
Tell callers exactly what to do. "Press pound when done" or "Say yes or no" is better than assuming they know.
### Allow Menu Repetition
Offer a "Press 9 to repeat this menu" option. Callers often miss options the first time.
### Set Appropriate Timeouts
For simple menus, 10 seconds is reasonable. For account numbers or complex input, allow 15-20 seconds. Too short frustrates users; too long wastes time.
### Confirm Critical Actions
Before processing payments, canceling services, or other important actions, read back the input and ask for confirmation.
```
You entered account number 1-2-3-4-5-6. Press 1 to confirm or 2 to re-enter.
```
### Test with Real Users
Have colleagues or beta users call your IVR. You'll discover confusing prompts, unclear options, and timing issues that aren't obvious during development.
);
}

---

# Page: /xml/stream

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'status-callback-params', title: 'Status Callback Parameters', level: 2 },
{ id: 'status-callback-events', title: 'Status Callback Events', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 },
{ id: 'next-steps', title: 'Next Steps', level: 2 },
];
return (
{/* Header Section */}
# The Stream Element
The Stream element lets you receive raw audio from active calls over a WebSocket connection in near real time. This enables powerful use cases like real-time transcription, sentiment analysis, and AI-powered call assistants.
### Key Capabilities
→
**Bidirectional streaming:** Send and receive audio in real-time
→
**Multiple audio tracks:** Stream inbound, outbound, or both tracks
→
**Flexible codecs:** Support for multiple audio formats and sample rates
→
**Event streaming:** Send playback, checkpoint, and control events via WebSocket
{/* Attributes */}
## Attributes
Attribute
Description
`bidirectional`
(boolean)
Specifies whether the audio being streamed over the WebSocket is bidirectional (read/write) or one-way (read-only).
If `true`, Vobiz accepts:
- **event:** Takes `playAudio` as the value
**media:** JSON object containing:
- **contentType:** audio/x-l16, audio/x-mulaw
- **sampleRate:** 8000, 16000
- **payload:** Base64-encoded raw audio
`audioTrack`
(string)
The audio track (inbound/outbound) that Vobiz will fork and stream to the WebSocket.
**Allowed values:** `inbound`, `outbound`, `both`
**Default:** `inbound`
**Note:** When bidirectional is true, audioTrack should not be `outbound` or `both`.
`streamTimeout`
(integer)
Maximum duration (in seconds) for audio streaming. Streaming stops after this duration.
Must be a positive integer.
**Default:** `86400` (24 hours)
`statusCallbackUrl`
(string)
URL notified when:
- Audio stream is connected
- Audio stream is stopped intentionally or due to timeout
- Audio stream failed or disconnected
`statusCallbackMethod`
(string)
HTTP method used to invoke statusCallbackUrl.
**Allowed values:** `GET`, `POST`
**Default:** `POST`
`contentType`
(string)
Preferred audio codec and sampling rate.
**Allowed values:**
- `audio/x-l16;rate=8000`
- `audio/x-l16;rate=16000`
- `audio/x-mulaw;rate=8000`
**Default:** `audio/x-l16;rate=8000`
`extraHeaders`
(string)
Key-value pairs sent to the WebSocket service with the audio stream.
**Example:** `test1=12,test2=123`
**Max length:** 512 bytes
**Allowed characters:** [A-Z], [a-z], [0-9]
`keepCallAlive`
(boolean)
If `true`, this stream element runs alone. Subsequent XML elements execute only after the stream disconnects.
**Allowed values:** `true`, `false`
**Default:** `false`
{/* Status Callback Parameters */}
## Parameters Sent to statusCallbackUrl
This information is sent to statusCallbackUrl when an event is triggered.
Parameter
Description
`bidirectional`
(boolean)
Indicates whether the audio stream was bidirectional (read/write) or one-way (read-only).
`audioTrack`
(string)
The audio track that Vobiz forked and streamed. Values: `inbound`, `outbound`, `both`
`streamTimeout`
(integer)
Maximum duration (in seconds) that audio was streamed. Default: 86400 (24 hours)
`statusCallbackUrl`
(string)
URL that received the notification of stream events.
`statusCallbackMethod`
(string)
HTTP method used (GET or POST). Default: POST
`contentType`
(string)
Audio codec and sampling rate that was used.
`extraHeaders`
(string)
Key-value pairs that were sent along with the audio stream.
`keepCallAlive`
(boolean)
Indicates whether stream was executed alone before continuing with subsequent XML elements.
{/* Status Callback Events */}
## Status Callback Events
When you configure a `statusCallbackUrl`, Vobiz sends HTTP POST/GET requests to that URL when specific stream lifecycle events occur. These are separate from WebSocket events and are useful for logging, monitoring, and triggering business logic.
### HTTP Callbacks vs WebSocket Events
**HTTP Status Callbacks** (sent to statusCallbackUrl):
- StartStream, PlayedStream, StopStream events
- Sent via HTTP POST/GET to your web server
- For logging, monitoring, and triggering workflows
**WebSocket Events** (sent via WebSocket connection):
- start, media, stop, playedStream, clearedAudio events
- Sent through the WebSocket connection in real-time
- For audio streaming and real-time interaction
{/* StartStream Event */}
StartStream
Stream Started
Fired when the WebSocket connection is successfully established and audio streaming begins.
```
POST /stream-status HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded
From=918071387423
To=919624705678
CallUUID=9a0e0208-d01a-4572-9a04-fe583a05ac53
Event=StartStream
StreamID=227d997a-0af4-447c-a3f3-b243e902e527
ServiceURL=ws://stream.vobiz.ai/ws
ParentAuthID=MA_PU0XU668
status_callback_url=https://yourapp.com/stream-status
status_callback_method=POST
Timestamp=2025-11-06 09:58:40
```
{/* PlayedStream Event */}
PlayedStream
Checkpoint Reached
Fired when audio queued before a checkpoint event has been successfully played to the caller. The `Name` parameter contains the checkpoint name you specified.
**Note:** This event is only sent if you send a `checkpoint` event via WebSocket and the audio plays successfully. If playback is interrupted, this event may not fire.
```
POST /stream-status HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded
From=918071387423
To=919624705678
CallUUID=9a0e0208-d01a-4572-9a04-fe583a05ac53
Event=PlayedStream
StreamID=227d997a-0af4-447c-a3f3-b243e902e527
Name=first
ParentAuthID=MA_PU0XU668
status_callback_url=https://yourapp.com/stream-status
status_callback_method=POST
Timestamp=2025-11-06 09:58:46
```
{/* StopStream Event */}
StopStream
Stream Ended
Fired when the audio streaming session ends. This can happen due to:
- Stream timeout (streamTimeout reached)
- Call ended by either party
- WebSocket connection closed
- Network error or disconnection
```
POST /stream-status HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded
From=918071387423
To=919624705678
CallUUID=9a0e0208-d01a-4572-9a04-fe583a05ac53
Event=StopStream
StreamID=227d997a-0af4-447c-a3f3-b243e902e527
ParentAuthID=MA_PU0XU668
status_callback_url=https://yourapp.com/stream-status
status_callback_method=POST
Timestamp=2025-11-06 09:58:50
```
{/* Common Parameters */}
### Common Parameters in All Events
Parameter
Description
`CallUUID`
Unique identifier for the call
`StreamID`
Unique identifier for this streaming session
`Event`
Event type: StartStream, PlayedStream, or StopStream
`From`
Caller's phone number
`To`
Called phone number
`Timestamp`
When the event occurred
`Name`
Checkpoint name (PlayedStream only)
`ServiceURL`
WebSocket URL used for streaming (StartStream only)
{/* Example Handler */}
### Example: Handling Status Callbacks
```
app.post('/stream-status', (req, res) => {
const { Event, StreamID, CallUUID, Name, Timestamp } = req.body;
switch(Event) {
case 'StartStream':
console.log(\`Stream started: \${StreamID} for call \${CallUUID}\`);
// Log to database, initialize session, etc.
break;
case 'PlayedStream':
console.log(\`Checkpoint "\${Name}" reached for stream \${StreamID}\`);
// Track checkpoint completion, trigger next action
break;
case 'StopStream':
console.log(\`Stream ended: \${StreamID} at \${Timestamp}\`);
// Clean up resources, finalize session, send notifications
break;
default:
console.log(\`Unknown event: \${Event}\`);
}
// Always respond with 200 OK
res.status(200).send('OK');
});
```
{/* Examples */}
## Examples
### Basic Audio Stream
```
wss://stream.vobiz.ai/stream
```
This streams inbound audio (default) to your WebSocket server at the specified URL.
### Bidirectional Audio Stream
```
wss://stream.vobiz.ai/stream
```
This enables bidirectional streaming with 16kHz sample rate, keeps the call alive during streaming, and sends status updates to your callback URL.
### Stream Both Tracks with Timeout
```
wss://stream.vobiz.ai/stream
Thank you for calling. We're processing your request.
```
This streams both inbound and outbound audio for up to 1 hour, includes custom headers, and continues to subsequent XML elements after streaming ends.
{/* Next Steps */}
## Next Steps
### Initiate a Stream
Learn how to establish a WebSocket connection and start streaming audio from active calls.
### Stream Events Overview
Understand how to send events like playAudio, clearAudio, and checkpoint via WebSocket.
### Checkpoint Event
Send checkpoint events to confirm audio playback completion and manage event queues.
### Play Audio Event
Transmit audio through WebSocket for bidirectional audio streaming use cases.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/stream/initiate

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'xml-setup', title: 'XML Setup', level: 2 },
{ id: 'websocket-connection', title: 'WebSocket Connection', level: 2 },
{ id: 'connection-flow', title: 'Connection Flow', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 },
{ id: 'troubleshooting', title: 'Troubleshooting', level: 2 },
];
return (
{/* Header Section */}
# Initiate a Stream
Learn how to establish a WebSocket connection and start streaming audio from active calls using the Stream XML element.
### What Happens
When Vobiz encounters an `Stream` element in your XML response:
- Vobiz initiates a WebSocket connection to your specified URL
- Once connected, raw audio packets are streamed in real-time
- Your application can process, analyze, or forward the audio
- For bidirectional streams, your app can also send audio back to the call
{/* XML Setup */}
## XML Setup
To initiate an audio stream, include the `Stream` element in your XML response with the WebSocket URL:
```
wss://stream.vobiz.ai/stream
```
💡 Understanding keepCallAlive
**Without `keepCallAlive="true"`:** The `<Stream>` element starts the background stream process and finishes immediately. Since there are no more elements in your XML response, the call hits "End Of XML Instructions" and hangs up instantly.
**With `keepCallAlive="true"`:** The system explicitly waits for the stream to finish (disconnect/error/timeout) before moving on or hanging up. This keeps the call open without needing a `<Pause>` element.
Note: `keepCallAlive` requires `bidirectional="true"`. Use this attribute instead of `<Pause>` for a cleaner implementation.
### Key Configuration Parameters
→
**WebSocket URL:** The text content of the element (e.g., `wss://stream.vobiz.ai/stream`)
→
**bidirectional:** Set to `true` to enable sending audio back to the call
→
**streamTimeout:** Maximum streaming duration in seconds (default: 86400 / 24 hours)
→
**keepCallAlive:** Set to `true` to prevent the call from hanging up when the stream ends or encounters an error
{/* WebSocket Connection */}
## WebSocket Connection
Your WebSocket server must be ready to accept connections from Vobiz. Here's what the initial connection looks like:
### Connection Start Message
```
{
"event": "start",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662",
"accountId": "MA_2210JXXN",
"callId": "CALL_abc123xyz",
"from": "+14155551111",
"to": "+14155552222",
"direction": "inbound",
"contentType": "audio/x-mulaw;rate=8000",
"audioTrack": "inbound"
}
```
This message provides context about the call and audio stream configuration.
### Audio Data Messages
```
{
"event": "media",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662",
"media": {
"payload": "base64-encoded-audio-data...",
"contentType": "audio/x-mulaw",
"sampleRate": 8000,
"timestamp": 1634567890123
}
}
```
Vobiz sends these messages continuously, containing base64-encoded raw audio data.
### Stream Stop Message
```
{
"event": "stop",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662",
"reason": "call_ended"
}
```
The connection closes gracefully when the call ends or the stream timeout is reached.
{/* Connection Flow */}
## Connection Flow
1
**Vobiz receives your XML response** containing the Stream element
2
**WebSocket connection established** to your specified URL
3
**"start" event sent** with call metadata and stream configuration
4
**Continuous "media" events** stream audio packets in real-time
5
**Bidirectional streams (optional):** Your app can send playAudio events back to Vobiz
6
**"stop" event sent** when call ends or timeout is reached
7
**WebSocket connection closes** gracefully
{/* Examples */}
## Implementation Examples
### Node.js WebSocket Server
```
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });
wss.on('connection', (ws) => {
console.log('Vobiz connected to audio stream');
ws.on('message', (message) => {
const data = JSON.parse(message);
if (data.event === 'start') {
console.log('Stream started:', data.streamId);
console.log('Call from:', data.from, 'to:', data.to);
} else if (data.event === 'media') {
// Process base64-encoded audio data
const audioBuffer = Buffer.from(data.media.payload, 'base64');
console.log('Received audio chunk:', audioBuffer.length, 'bytes');
// Your audio processing logic here
// e.g., send to transcription service, save to file, etc.
} else if (data.event === 'stop') {
console.log('Stream stopped:', data.reason);
}
});
ws.on('close', () => {
console.log('WebSocket connection closed');
});
});
console.log('WebSocket server listening on port 8080');
```
### Python WebSocket Handler
```
import asyncio
async def handle_audio_stream(websocket, path):
print("Vobiz connected to audio stream")
async for message in websocket:
data = json.loads(message)
if data['event'] == 'start':
print(f"Stream started: {data['streamId']}")
print(f"Call from {data['from']} to {data['to']}")
elif data['event'] == 'media':
# Decode base64 audio data
audio_bytes = base64.b64decode(data['media']['payload'])
print(f"Received audio chunk: {len(audio_bytes)} bytes")
# Your audio processing logic here
# e.g., send to transcription, analysis, etc.
elif data['event'] == 'stop':
print(f"Stream stopped: {data.get('reason', 'unknown')}")
break
async def main():
async with websockets.serve(handle_audio_stream, "0.0.0.0", 8080):
print("WebSocket server listening on port 8080")
await asyncio.Future()  # run forever
if __name__ == "__main__":
asyncio.run(main())
```
### Vobiz XML Response with Stream
```
This call is being recorded for quality assurance.
wss://stream.vobiz.ai/stream
+14155551234
```
This example streams both inbound and outbound audio with 8kHz sample rate (Mu-law), includes custom session headers, and sends status updates to your callback URL.
{/* Troubleshooting */}
## Troubleshooting
### Invalid Stream Configuration
**Problem:** If your call hangs up with `End Of XML Instructions`, you likely have an invalid configuration.
**Solution:** The media server does not support `audioTrack="both"` when `bidirectional="true"`. You must set `audioTrack="inbound"` (or remove the attribute) for bidirectional streams.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/stream/stream-events

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'event-types', title: 'Event Types', level: 2 },
{ id: 'event-flow', title: 'Event Flow', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 },
];
return (
{/* Header Section */}
# Stream Events Overview
You can utilize the WebSocket connection to stream events from your application to Vobiz. With this connection, you can play audio, interrupt and clear buffered audio, and send a checkpoint event to indicate the completion of playback.
### Prerequisites
To use stream events, you must:
→
Set `bidirectional="true"` on the Stream element
→
Have an active WebSocket connection established by Vobiz
→
Send events as JSON messages through the WebSocket
{/* Event Types */}
## Event Types
1. playAudio Event
Transmit audio through the WebSocket to be played on the call. When the bidirectional attribute is set to true, Vobiz can deliver the audio transmitted from your application to the party on the call.
**Key Attributes:**
- **event:** `playAudio`
- **media:** Object containing contentType, sampleRate, and base64-encoded payload
Learn more about playAudio →
2. clearAudio Event
The clearAudio event interrupts audio previously sent to Vobiz via the playAudio event. Vobiz clears all buffered media events, enabling you to initiate new playAudio events tailored to a specific use case.
**Key Attributes:**
- **event:** `clearAudio`
- **streamId:** Unique identifier for the audio stream
Learn more about clearAudio →
3. checkpoint Event
Send a checkpoint event via WebSocket when the desired audio events are queued. Vobiz will respond with `playedStream`, indicating that audio events buffered before the Checkpoint were successfully played out to the end user.
**Key Attributes:**
- **event:** `checkpoint`
- **streamId:** Unique identifier for the audio stream
- **name:** Name of the checkpoint you use to recognize upon receiving acknowledgment
Learn more about checkpoint →
{/* Event Flow */}
## Event Flow
Here's how stream events flow between your application and Vobiz:
→
#### Your App → Vobiz
Send events through the WebSocket to control audio playback:
- `playAudio` - Play audio to the caller
- `clearAudio` - Interrupt and clear buffered audio
- `checkpoint` - Mark playback completion points
←
#### Vobiz → Your App
Receive acknowledgments and stream data from Vobiz:
- `start` - Stream connection established
- `media` - Continuous audio packets from the call
- `playedStream` - Checkpoint acknowledgment
- `clearedAudio` - Clear audio acknowledgment
- `stop` - Stream connection ended
**Important:** The `playedStream` event will only be emitted if the preceding events were played successfully. If playback fails or is interrupted, you may not receive this acknowledgment.
{/* Examples */}
## Examples
### Bidirectional XML Configuration
```
wss://stream.vobiz.ai/stream
```
The `bidirectional="true"` attribute is required to send playAudio, clearAudio, and checkpoint events.
### Typical Event Sequence
```
// 1. Vobiz sends 'start' event
{
"event": "start",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662",
"callId": "CALL_abc123xyz"
}
// 2. Your app sends playAudio event (greeting)
{
"event": "playAudio",
"media": {
"contentType": "audio/x-l16",
"sampleRate": 8000,
"payload": "base64-encoded-audio..."
}
}
// 3. Your app sends checkpoint to mark greeting completion
{
"event": "checkpoint",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662",
"name": "customer greeting audio"
}
// 4. Vobiz responds with playedStream (greeting played successfully)
{
"event": "playedStream",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662",
"name": "customer greeting audio"
}
// 5. User speaks - Vobiz sends media events
{
"event": "media",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662",
"media": {
"payload": "base64-user-audio...",
"contentType": "audio/x-l16",
"sampleRate": 8000
}
}
// 6. Your app decides to interrupt with new audio
{
"event": "clearAudio",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662"
}
// 7. Vobiz acknowledges the clear
{
"sequenceNumber": 0,
"event": "clearedAudio",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662"
}
// 8. Your app sends new playAudio event
{
"event": "playAudio",
"media": {
"contentType": "audio/x-l16",
"sampleRate": 8000,
"payload": "base64-new-audio..."
}
}
```
### Node.js Implementation
```
const WebSocket = require('ws');
let streamId = null;
wss.on('connection', (ws) => {
ws.on('message', (message) => {
const data = JSON.parse(message);
if (data.event === 'start') {
streamId = data.streamId;
console.log('Stream started:', streamId);
// Play a greeting audio
sendPlayAudio(ws, greetingAudioBase64);
// Send checkpoint to track when greeting finishes
sendCheckpoint(ws, streamId, 'greeting-complete');
}
if (data.event === 'playedStream') {
console.log('Checkpoint reached:', data.name);
// Greeting played successfully - continue with next action
}
if (data.event === 'media') {
// Process incoming audio
const audioData = Buffer.from(data.media.payload, 'base64');
// ... analyze, transcribe, etc.
}
});
});
function sendPlayAudio(ws, audioBase64) {
ws.send(JSON.stringify({
event: 'playAudio',
media: {
contentType: 'audio/x-l16',
sampleRate: 8000,
payload: audioBase64
}
}));
}
function sendCheckpoint(ws, streamId, checkpointName) {
ws.send(JSON.stringify({
event: 'checkpoint',
streamId: streamId,
name: checkpointName
}));
}
function sendClearAudio(ws, streamId) {
ws.send(JSON.stringify({
event: 'clearAudio',
streamId: streamId
}));
}
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/stream/checkpoint-event

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'request-response', title: 'Request & Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 },
];
return (
{/* Header Section */}
# Checkpoint Event
Send a checkpoint event via WebSocket when the desired audio events are queued. Vobiz will respond with `playedStream`, indicating that audio events buffered before the Checkpoint were successfully played out to the end user.
### Purpose
The checkpoint event acts as a marker in your audio event queue. When Vobiz finishes playing all audio events that were sent before the checkpoint, it sends a `playedStream` acknowledgment back to your application. This allows you to:
→
Track playback completion of specific audio segments
→
Synchronize your application logic with audio playback
→
Implement multi-turn conversations with timing control
{/* Attributes */}
## Attributes
Attribute
Description
`event`
(string)
Required
Indicates the event type. Use `checkpoint` as the value expected.
`name`
(string)
Required
Name of the checkpoint that you use to recognize upon receiving the acknowledgment.
**Example:** `"customer greeting audio"`, `"main menu prompt"`
`streamId`
(string)
Required
A unique identifier generated for each audio stream.
This value is provided by Vobiz in the initial "start" event when the WebSocket connection is established.
{/* Request & Response */}
## Request & Response
### Request Format
Send this JSON message through the WebSocket to Vobiz:
```
{
"event": "checkpoint",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662",
"name": "customer greeting audio"
}
```
### Response Format
When the checkpoint is reached (all previous audio has been played), Vobiz responds with:
```
{
"event": "playedStream",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662",
"name": "customer greeting audio"
}
```
**Important Note:**
The `playedStream` event will only be emitted if the preceding events were played successfully. If playback is interrupted (e.g., by a clearAudio event or call disconnection), you may not receive this acknowledgment.
{/* Examples */}
## Examples
### Complete Event Sequence
```
// 1. Your app sends playAudio event (e.g., greeting message)
ws.send(JSON.stringify({
event: 'playAudio',
media: {
contentType: 'audio/x-l16',
sampleRate: 8000,
payload: greetingAudioBase64
}
}));
// 2. Immediately send checkpoint to mark this audio segment
ws.send(JSON.stringify({
event: 'checkpoint',
streamId: '20170ada-f610-433b-8758-c02a2aab3662',
name: 'customer greeting audio'
}));
// 3. Continue with your logic...
// Later, when Vobiz finishes playing the audio:
// 4. Vobiz sends playedStream acknowledgment
{
event: 'playedStream',
streamId: '20170ada-f610-433b-8758-c02a2aab3662',
name: 'customer greeting audio'
}
// 5. Your app receives the acknowledgment and proceeds
ws.on('message', (message) => {
const data = JSON.parse(message);
if (data.event === 'playedStream' && data.name === 'customer greeting audio') {
console.log('Greeting completed successfully!');
// Now you can proceed with next step (e.g., collect user input)
}
});
```
### Node.js Implementation
```
const WebSocket = require('ws');
let currentStreamId = null;
let conversationState = 'greeting';
wss.on('connection', (ws) => {
ws.on('message', (message) => {
const data = JSON.parse(message);
// Handle stream start
if (data.event === 'start') {
currentStreamId = data.streamId;
console.log('Stream started:', currentStreamId);
// Play greeting audio
playGreeting(ws);
}
// Handle checkpoint acknowledgments
if (data.event === 'playedStream') {
console.log(\`Checkpoint '\${data.name}' reached\`);
// Transition based on completed checkpoint
if (data.name === 'greeting') {
conversationState = 'main-menu';
playMainMenu(ws);
} else if (data.name === 'main-menu') {
conversationState = 'collecting-input';
// Start listening for DTMF or speech input
} else if (data.name === 'option-1-prompt') {
conversationState = 'processing-option-1';
// Handle option 1 logic
}
}
// Handle incoming audio (for speech recognition, etc.)
if (data.event === 'media') {
const audioBuffer = Buffer.from(data.media.payload, 'base64');
// Process audio based on current conversation state
}
});
});
function playGreeting(ws) {
// Send greeting audio
ws.send(JSON.stringify({
event: 'playAudio',
media: {
contentType: 'audio/x-l16',
sampleRate: 8000,
payload: greetingAudioBase64
}
}));
// Mark checkpoint
ws.send(JSON.stringify({
event: 'checkpoint',
streamId: currentStreamId,
name: 'greeting'
}));
}
function playMainMenu(ws) {
// Send main menu prompt
ws.send(JSON.stringify({
event: 'playAudio',
media: {
contentType: 'audio/x-l16',
sampleRate: 8000,
payload: mainMenuAudioBase64
}
}));
// Mark checkpoint
ws.send(JSON.stringify({
event: 'checkpoint',
streamId: currentStreamId,
name: 'main-menu'
}));
}
```
This example demonstrates using checkpoints to manage a multi-turn conversation flow, transitioning between states only when the current audio has finished playing.
### Python AsyncIO Example
```
import asyncio
stream_id = None
conversation_state = 'greeting'
async def handle_checkpoint(ws, checkpoint_name):
"""Send checkpoint and wait for acknowledgment"""
checkpoint_msg = {
'event': 'checkpoint',
'streamId': stream_id,
'name': checkpoint_name
}
await ws.send(json.dumps(checkpoint_msg))
print(f"Checkpoint '{checkpoint_name}' sent")
async def play_audio_with_checkpoint(ws, audio_base64, checkpoint_name):
"""Play audio and mark with checkpoint"""
# Send audio
play_msg = {
'event': 'playAudio',
'media': {
'contentType': 'audio/x-l16',
'sampleRate': 8000,
'payload': audio_base64
}
}
await ws.send(json.dumps(play_msg))
# Send checkpoint
await handle_checkpoint(ws, checkpoint_name)
async def handle_stream(websocket, path):
global stream_id, conversation_state
async for message in websocket:
data = json.loads(message)
if data['event'] == 'start':
stream_id = data['streamId']
print(f"Stream started: {stream_id}")
# Play greeting with checkpoint
await play_audio_with_checkpoint(
websocket,
greeting_audio_base64,
'greeting'
)
elif data['event'] == 'playedStream':
checkpoint = data['name']
print(f"Checkpoint reached: {checkpoint}")
# State transitions based on checkpoint
if checkpoint == 'greeting':
conversation_state = 'main-menu'
await play_audio_with_checkpoint(
websocket,
main_menu_audio_base64,
'main-menu'
)
elif checkpoint == 'main-menu':
conversation_state = 'waiting-input'
print("Ready for user input")
elif data['event'] == 'media':
# Process incoming audio
audio_bytes = base64.b64decode(data['media']['payload'])
# ... handle audio processing
async def main():
async with websockets.serve(handle_stream, "0.0.0.0", 8080):
print("WebSocket server running on port 8080")
await asyncio.Future()
if __name__ == "__main__":
asyncio.run(main())
```
{/* Best Practices */}
## Best Practices
### Use Descriptive Checkpoint Names
Give your checkpoints meaningful names that clearly indicate what audio segment they represent. This makes debugging and maintaining your code much easier.
### Don't Rely on Checkpoints for Critical Logic
Remember that playedStream acknowledgments may not arrive if the call is disconnected or audio is interrupted. Always have fallback logic for timeout scenarios.
### Send Checkpoints Immediately After Audio
For the most accurate timing, send your checkpoint event immediately after the corresponding playAudio event. This ensures the checkpoint marks exactly when that audio segment finishes.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/stream/clear-audio

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'request-response', title: 'Request & Response', level: 2 },
{ id: 'use-cases', title: 'Use Cases', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 },
];
return (
{/* Header Section */}
# Clear Stream
The clearAudio event interrupts audio previously sent to Vobiz via the playAudio event. Vobiz clears all buffered media events, enabling you to initiate new playAudio events tailored to a specific use case.
### When to Use clearAudio
You can send a clearAudio event to interrupt the audio that has been sent to Vobiz. This will clear all the buffered audio. Common scenarios include:
→
**Barge-in:** User starts speaking while AI prompt is playing
→
**Context switch:** User changes topic mid-conversation
→
**Error recovery:** Cancel current playback and play error message
→
**Priority messages:** Interrupt to play urgent information
{/* Attributes */}
## Attributes
Attribute
Description
`event`
(string)
Required
Indicates the event type. Use `clearAudio` to clear all the buffered audio.
`streamId`
(string)
Required
A unique identifier generated for each audio stream.
This value is provided by Vobiz in the initial "start" event when the WebSocket connection is established.
{/* Request & Response */}
## Request & Response
### Request Format
Send this JSON message through the WebSocket to Vobiz to clear buffered audio:
```
{
"event": "clearAudio",
"streamId": "b77e037d-4119-44b5-902d-25826b654539"
}
```
### Response Format
Vobiz acknowledges the clearAudio event with a `clearedAudio` response:
```
{
"sequenceNumber": 0,
"event": "clearedAudio",
"streamId": "20170ada-f610-433b-8758-c02a2aab3662"
}
```
The `sequenceNumber` field helps track the order of events in the stream.
**Important:**
After sending clearAudio, all previously sent playAudio events that haven't been played yet are discarded. Any pending checkpoint events will not receive acknowledgments. You can immediately send new playAudio events after clearAudio to replace the interrupted audio.
{/* Use Cases */}
## Common Use Cases
1. Voice Assistant Barge-In
When building conversational AI, users often start speaking before the AI finishes its response. Detect user speech and send clearAudio to stop the AI from continuing its playback.
```
// Detect user speech in incoming audio
if (data.event === 'media') {
const audioLevel = detectAudioLevel(data.media.payload);
// If user starts speaking while AI is talking
if (audioLevel > SPEECH_THRESHOLD && isAIPlaying) {
console.log('User barge-in detected');
// Clear the buffered AI audio
ws.send(JSON.stringify({
event: 'clearAudio',
streamId: currentStreamId
}));
isAIPlaying = false;
// Start listening for user's full input
startSpeechRecognition();
}
}
```
2. Dynamic Content Updates
If you're playing a long audio message and receive updated information (e.g., real-time data), you can interrupt the current playback and play the updated content.
```
// Receive real-time update (e.g., stock price change)
async function handleDataUpdate(newData) {
// Clear currently playing audio
await sendClearAudio(ws, streamId);
// Wait for acknowledgment
await waitForClearedAudio();
// Generate and play updated audio with new information
const updatedAudio = await generateSpeech(
\`Update: The price is now \${newData.price}\`
);
await sendPlayAudio(ws, updatedAudio);
}
```
3. Error Handling & Recovery
When an error occurs during a transaction or API call, interrupt the current flow and play an appropriate error message.
```
try {
// Attempting some operation
await processPayment(userId, amount);
// Play success audio
await sendPlayAudio(ws, successAudioBase64);
} catch (error) {
console.error('Payment failed:', error);
// Clear any pending audio
await sendClearAudio(ws, streamId);
// Play error message
const errorAudio = await generateSpeech(
'Sorry, there was an error processing your payment. Please try again.'
);
await sendPlayAudio(ws, errorAudio);
}
```
{/* Examples */}
## Implementation Examples
### Node.js Example
```
const WebSocket = require('ws');
let currentStreamId = null;
let isPlaying = false;
wss.on('connection', (ws) => {
ws.on('message', (message) => {
const data = JSON.parse(message);
if (data.event === 'start') {
currentStreamId = data.streamId;
console.log('Stream started:', currentStreamId);
// Start playing introduction
playIntroduction(ws);
}
if (data.event === 'playedStream') {
isPlaying = false;
console.log('Audio completed:', data.name);
}
if (data.event === 'clearedAudio') {
console.log('Audio cleared successfully');
// Now safe to send new playAudio events
}
if (data.event === 'media') {
// Detect if user is speaking
const audioBuffer = Buffer.from(data.media.payload, 'base64');
const speechDetected = detectSpeech(audioBuffer);
if (speechDetected && isPlaying) {
// User is interrupting - clear current audio
clearAudio(ws);
}
}
});
});
function playIntroduction(ws) {
isPlaying = true;
ws.send(JSON.stringify({
event: 'playAudio',
media: {
contentType: 'audio/x-l16',
sampleRate: 8000,
payload: introAudioBase64
}
}));
ws.send(JSON.stringify({
event: 'checkpoint',
streamId: currentStreamId,
name: 'introduction'
}));
}
function clearAudio(ws) {
console.log('Clearing buffered audio...');
ws.send(JSON.stringify({
event: 'clearAudio',
streamId: currentStreamId
}));
isPlaying = false;
}
function detectSpeech(audioBuffer) {
// Implement your speech detection logic
// Return true if speech is detected above threshold
return audioBuffer.length > 0 && calculateRMS(audioBuffer) > 0.02;
}
function calculateRMS(buffer) {
let sum = 0;
for (let i = 0; i
### Python Example
```
import asyncio
stream_id = None
is_playing = False
async def clear_audio(websocket):
"""Clear buffered audio"""
global is_playing
clear_msg = {
'event': 'clearAudio',
'streamId': stream_id
}
await websocket.send(json.dumps(clear_msg))
is_playing = False
print("Sent clearAudio event")
async def play_audio(websocket, audio_base64, checkpoint_name=None):
"""Play audio with optional checkpoint"""
global is_playing
# Send playAudio
play_msg = {
'event': 'playAudio',
'media': {
'contentType': 'audio/x-l16',
'sampleRate': 8000,
'payload': audio_base64
}
}
await websocket.send(json.dumps(play_msg))
is_playing = True
# Send checkpoint if provided
if checkpoint_name:
checkpoint_msg = {
'event': 'checkpoint',
'streamId': stream_id,
'name': checkpoint_name
}
await websocket.send(json.dumps(checkpoint_msg))
async def handle_stream(websocket, path):
global stream_id, is_playing
async for message in websocket:
data = json.loads(message)
if data['event'] == 'start':
stream_id = data['streamId']
print(f"Stream started: {stream_id}")
# Play welcome message
await play_audio(websocket, welcome_audio_base64, 'welcome')
elif data['event'] == 'playedStream':
is_playing = False
print(f"Checkpoint reached: {data['name']}")
elif data['event'] == 'clearedAudio':
print("Audio cleared - ready for new playback")
elif data['event'] == 'media':
# Detect user speech
audio_bytes = base64.b64decode(data['media']['payload'])
speech_detected = detect_speech(audio_bytes)
if speech_detected and is_playing:
print("User interruption detected")
await clear_audio(websocket)
def detect_speech(audio_bytes):
"""Detect if audio contains speech"""
# Implement your speech detection logic
# Simple RMS-based detection as example
if len(audio_bytes) == 0:
return False
rms = sum(b * b for b in audio_bytes) / len(audio_bytes)
return rms > 0.02  # Threshold
async def main():
async with websockets.serve(handle_stream, "0.0.0.0", 8080):
print("WebSocket server running on port 8080")
await asyncio.Future()
if __name__ == "__main__":
asyncio.run(main())
```
{/* Best Practices */}
## Best Practices
### Wait for clearedAudio Acknowledgment
Before sending new playAudio events after clearAudio, it's best practice to wait for the `clearedAudio` acknowledgment to ensure the buffer is fully cleared.
### Track Playback State
Maintain a state variable to track whether audio is currently playing. This helps you decide when to send clearAudio events and avoid unnecessary interruptions.
### Use Appropriate Detection Thresholds
When implementing barge-in, tune your speech detection threshold carefully to avoid false positives from background noise while still being responsive to actual user speech.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/stream/play-audio

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'audio-format', title: 'Audio Format Requirements', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 },
];
return (
{/* Header Section */}
# Play Audio Event
You can utilize the `playAudio` event to transmit audio through the WebSocket. When the bidirectional attribute is set to true, Vobiz can deliver the audio transmitted from your application to the party on the call.
### Prerequisites
→
Stream element must have `bidirectional="true"`
→
Active WebSocket connection established by Vobiz
→
Audio must be base64-encoded in the correct format (PCM or μ-law)
{/* Attributes */}
## Attributes
Attribute
Description
`event`
(string)
Required
Indicates the event type. `playAudio` is the value required to transmit audio over the WebSocket.
`media`
(object)
Required
An object containing media metadata and payload.
Media Object Properties:
**contentType** (string, required): The audio codec format
- `audio/x-l16` - Linear PCM 16-bit
- `audio/x-mulaw` - μ-law encoded
**sampleRate** (integer, required): Sample rate of the audio transmitted
- `8000` - 8kHz (standard telephony)
- `16000` - 16kHz (wideband)
**payload** (string, required): Base64-encoded string of raw audio
{/* Audio Format Requirements */}
## Audio Format Requirements
### Supported Formats
#### Linear PCM (audio/x-l16)
- **Format:** 16-bit linear PCM
- **Endianness:** Little-endian
- **Sample rates:** 8000 Hz or 16000 Hz
- **Channels:** Mono (1 channel)
- **Encoding:** Base64
#### μ-law (audio/x-mulaw)
- **Format:** μ-law compressed
- **Sample rate:** 8000 Hz
- **Channels:** Mono (1 channel)
- **Encoding:** Base64
- **Use case:** Lower bandwidth
**Important:**
- Audio must be raw PCM or μ-law data (no WAV headers or file containers)
- The contentType and sampleRate must match your actual audio data
- For best quality, use 16kHz sample rate with audio/x-l16
- Each playAudio event should contain a reasonable chunk size (typically 20-60ms of audio)
{/* Examples */}
## Examples
### Request Format
```
{
"event": "playAudio",
"media": {
"contentType": "audio/x-l16",
"sampleRate": 8000,
"payload": "base64 encoded raw audio..."
}
}
```
### Node.js Implementation
```
const WebSocket = require('ws');
const fs = require('fs');
// Example: Convert text to speech and send via WebSocket
async function textToSpeechAndPlay(ws, text) {
try {
// 1. Generate audio from text (using TTS service)
const audioBuffer = await generateSpeech(text, {
format: 'pcm',
sampleRate: 8000,
bitDepth: 16
});
// 2. Convert to base64
const audioBase64 = audioBuffer.toString('base64');
// 3. Send playAudio event
const playAudioEvent = {
event: 'playAudio',
media: {
contentType: 'audio/x-l16',
sampleRate: 8000,
payload: audioBase64
}
};
ws.send(JSON.stringify(playAudioEvent));
console.log('Sent audio:', text);
} catch (error) {
console.error('Error generating/sending audio:', error);
}
}
// Example: Stream audio from file in chunks
function streamAudioFile(ws, filepath) {
// Read raw PCM audio file
const audioData = fs.readFileSync(filepath);
// Calculate chunk size (e.g., 20ms of audio)
const sampleRate = 8000;
const bytesPerSample = 2; // 16-bit = 2 bytes
const chunkDuration = 0.020; // 20ms
const chunkSize = Math.floor(sampleRate * bytesPerSample * chunkDuration);
// Send audio in chunks
for (let i = 0; i
### Python Implementation
```
import asyncio
async def play_audio(websocket, audio_bytes, sample_rate=8000, content_type='audio/x-l16'):
"""Send playAudio event to Vobiz"""
# Encode audio as base64
audio_base64 = base64.b64encode(audio_bytes).decode('utf-8')
# Create playAudio event
play_audio_event = {
'event': 'playAudio',
'media': {
'contentType': content_type,
'sampleRate': sample_rate,
'payload': audio_base64
}
}
# Send to Vobiz
await websocket.send(json.dumps(play_audio_event))
print(f"Sent {len(audio_bytes)} bytes of audio")
async def text_to_speech_and_play(websocket, text):
"""Generate speech from text and play it"""
# 1. Generate audio from text (using TTS)
audio_bytes = await generate_speech(text, sample_rate=8000)
# 2. Send to Vobiz
await play_audio(websocket, audio_bytes, sample_rate=8000)
async def stream_audio_file(websocket, filepath):
"""Stream audio file in chunks"""
chunk_size = 320  # 20ms at 8kHz, 16-bit = 320 bytes
with open(filepath, 'rb') as f:
while True:
chunk = f.read(chunk_size)
if not chunk:
break
await play_audio(websocket, chunk, sample_rate=8000)
# Delay to simulate real-time playback
await asyncio.sleep(0.020)  # 20ms
print("Finished streaming audio file")
async def generate_speech(text, sample_rate=8000):
"""Generate speech from text (mock)"""
# This would call your TTS service
# (e.g., Google TTS, Amazon Polly, gTTS, pyttsx3, etc.)
# and return raw PCM audio bytes
# Placeholder - replace with actual TTS
return b'...'  # Raw PCM audio bytes
# Example usage in your WebSocket handler
async def handle_stream(websocket, path):
async for message in websocket:
data = json.loads(message)
if data['event'] == 'start':
# Play greeting when stream starts
await text_to_speech_and_play(
websocket,
"Hello! Welcome to Vobiz audio streaming."
)
elif data['event'] == 'media':
# Process incoming audio from call
pass
```
### Converting WAV to PCM
```
const fs = require('fs');
const wav = require('wav');
function convertWavToPCM(wavFilePath) {
return new Promise((resolve, reject) => {
const reader = new wav.Reader();
const chunks = [];
reader.on('format', (format) => {
console.log('WAV Format:', format);
// Ensure it's the right format
if (format.audioFormat !== 1) { // 1 = PCM
reject(new Error('Only PCM WAV files are supported'));
return;
}
if (format.channels !== 1) {
reject(new Error('Only mono audio is supported'));
return;
}
if (![8000, 16000].includes(format.sampleRate)) {
reject(new Error('Sample rate must be 8000 or 16000'));
return;
}
});
reader.on('data', (chunk) => {
chunks.push(chunk);
});
reader.on('end', () => {
const pcmData = Buffer.concat(chunks);
resolve(pcmData);
});
reader.on('error', reject);
fs.createReadStream(wavFilePath).pipe(reader);
});
}
// Usage
async function playWavFile(ws, wavFilePath) {
try {
// Convert WAV to raw PCM
const pcmData = await convertWavToPCM(wavFilePath);
// Convert to base64
const audioBase64 = pcmData.toString('base64');
// Send playAudio event
ws.send(JSON.stringify({
event: 'playAudio',
media: {
contentType: 'audio/x-l16',
sampleRate: 8000, // or 16000 depending on your file
payload: audioBase64
}
}));
console.log('WAV file sent successfully');
} catch (error) {
console.error('Error playing WAV file:', error);
}
}
```
{/* Best Practices */}
## Best Practices
### Match Audio Format to ContentType
Ensure your audio data format exactly matches the contentType and sampleRate you specify. Mismatches will result in distorted or garbled audio.
### Use Appropriate Chunk Sizes
Send audio in reasonable chunks (20-60ms). Too small chunks add overhead; too large chunks increase latency. For 8kHz 16-bit audio, 20ms = 320 bytes.
### Remove File Headers
Always send raw PCM or μ-law data without WAV headers or any file container metadata. Strip headers before base64-encoding.
### Use Checkpoints to Track Playback
Send checkpoint events after your playAudio events to get acknowledgments when audio finishes playing. This helps synchronize your application logic.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/conference

'use client';
return (
# The <Conference> Element
Connect the caller to a conference room. Multiple callers can join the same conference to participate in a group call.
## Example
```
You are joining the conference now.
MyConferenceRoom
```
The caller will be connected to a conference room named "MyConferenceRoom". If the room doesn't exist, it will be created automatically.
);
}

---

# Page: /xml/dial

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'nesting-rules', title: 'Nesting Rules', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'action-params', title: 'Parameters sent to action URL', level: 2 },
{ id: 'callback-params', title: 'Parameters sent to callbackUrl', level: 2 },
];
return (
{/* Header Section */}
# The Dial Element
You can use the Dial element to dial one or multiple phone numbers and connect them to the current caller. If the call is picked up, then the caller and receiver will be connected and can communicate until either party hangs up. If the call is not answered, or a busy signal is received, or the phone number dialed doesn't exist, the Dial element will end.
Upon completion of the call, Vobiz makes a GET or POST request to the action URL if one is provided. Based on the value of the Redirect element, the call flow will continue using the XML received from the action URL.
**Note:** A Number or User element must be present and nested inside Dial for the Dial element to work.
{/* Nesting Rules */}
## Nesting rules
- You must nest a Number or User element within the Dial element.
- Specify a single Number or User value to dial a single number or a SIP user.
- Specify multiple Number and User elements for simultaneous dialing.
{/* Attributes */}
## Attributes
Attribute
Description
`action`
string
Callback-retry configurable
Redirect to this URL after leaving Dial. See the table "Parameters sent to action URL" below for more information.
**Allowed values:** a fully qualified URL
`method`
string
Method used to send HTTP request to the action URL.
**Allowed values:** GET, POST
Defaults to POST.
`hangupOnStar`
boolean
The caller can press the * key to hang up on the called party but can continue with other operations depending on the application's response.
**Allowed values:** true, false
Defaults to false.
`timeLimit`
integer
Used to preset the duration (in seconds) of the call.
**Allowed values:** positive integer
Defaults to 14,400 seconds (4 hours).
**Note:** If timeLimit is ≥86,400 seconds, calls will be disconnected after 24 hours.
`timeout`
integer
The amount of time (in seconds) that the called party has to answer the call (pick up the phone or tap the answer button on a smart phone or SIP phone).
**Allowed values:** positive integer
No default value.
`callerId`
string
If set to a string, caller number will be set to this string value.
**Allowed values:** valid phone number
Defaults to the current caller's callerId.
`callerName`
string
If set to a string, caller name will be set to this string value.
**Allowed values:** Any string, maximum of 50 characters
Defaults to caller's callerName.
`confirmSound`
string
Callback-retry configurable
A remote URL fetched with a POST HTTP request that must return an XML response with Play, Wait, and/or Speak elements only (all others are ignored). The sound indicated by the XML is played to the called party when the call is answered.
**Note:** This parameter must be specified for confirmKey to work.
**Allowed values:** a fully qualified URL
`confirmTimeout`
string
Timeout starts after the call is answered. Entertained only if confirmSound parameter is passed without confirmKey
**Note:** confirmTimeout value should be greater than duration of confirmSound to auto answer the call once confirmSound is completely played.
Defaults to: 120
`confirmKey`
string
The digit to be pressed by the called party to accept the call. Used in conjunction with confirmSound.
**Allowed values:** any digit, #, *
`dialMusic`
string
Callback-retry configurable
Music to be played to the caller while the call is being connected. This is a remote URL fetched with a POST HTTP request. It must return an XML response with Play, Wait, and/or Speak elements only (all others are ignored). The sound indicated by the XML is played to the caller while the call is being connected.
Setting dialMusic to `real` plays the real ringtone of the called party. This is also the default behavior if dialMusic is not specified.
**Allowed values:** a fully qualified URL or `real`
`callbackUrl`
string
Callback-retry configurable
URL to be notified when one of these events occur:
- called party answers the call
- called party is connected with caller
- called party hangs up
- caller presses any digit. See the "Parameters sent to callbackUrl" table below for more information.
**Allowed values:** a fully qualified URL
Configuring confirmSound and confirmKey invokes the callbackUrl after the called party answers the call and before the called party confirms the call.
`callbackMethod`
string
Method used to notify callbackUrl.
**Allowed values:** GET, POST
Defaults to POST.
`redirect`
boolean
If set to false, don't redirect to action URL.
We expect an XML response from the action URL if this parameter is set to true. The call will be controlled based on the XML returned from the action URL.
**Allowed values:** true, false
Defaults to true.
`digitsMatch`
string
A list of digits that are sent to the callbackUrl when the digits pressed by the user match the digitsMatch parameter (A leg).
**Allowed values:** list of digit patterns separated by a comma. Example: digitsMatch="123,456,789"
`digitsMatchBLeg`
string
A list of digits that are sent to the callbackUrl when the digits pressed by the user match the digitsMatchBLeg parameter (B leg).
**Allowed values:** list of digit patterns separated by a comma. Example: digitsMatchBLeg="123,456,789"
`sipHeaders`
string
SIP headers are always prefixed with X-PH-.
For every HTTP request called by the dialed leg, the SIP headers will be present. Only [A-Z], [a-z], and [0-9] characters are allowed for SIP header key names and values, so that you can URL-encode the values.
**Allowed values:** list of SIP headers to send, separated by commas. Sent as key=value pair. For example, head1=val1,head2=val2,…,headN=valN.
{/* Parameters sent to action URL */}
## Parameters sent to action URL
These parameters are sent to the action URL after Dial is completed.
Parameter
Description
`DialRingStatus`
Indicates whether the Dial attempt rang.
**Allowed values:** true, false
`DialHangupCause`
The standard telephony hangup cause.
`DialStatus`
Status of the dial.
**Allowed values:** completed, busy, failed, cancel, timeout, no-answer
`DialALegUUID`
CallUUID of A leg.
`DialBLegUUID`
CallUUID of B leg. Empty if nobody answers.
{/* Parameters sent to callbackUrl */}
## Parameters sent to callbackUrl
These parameters are sent to the callbackUrl, if specified.
Parameter
Description
`DialAction`
**Allowed values:** answer, connected, hangup, digits
`DialBLegStatus`
Indicates whether B leg answered or hung up.
**Allowed values:** answer, connected, hangup
`DialALegUUID`
CallUUID of A leg.
`DialBLegUUID`
CallUUID of B leg. Empty if nobody answers.
`DialDigitsMatch`
The digits pressed by A leg and matching one digits combination set in digitsMatch attribute.
Only available when DialAction is set to digits.
`DialDigitsPressedBy`
Returns the leg of the call on which the digits were pressed — ALeg or BLeg.
`DialBLegDuration`
Dial duration in seconds from B leg. Only available when DialAction is set to hangup.
`DialBLegBillDuration`
Dial duration in seconds billed from B leg. Only available when DialAction is set to hangup.
`DialBLegFrom`
Dial caller number or SIP endpoint for B leg. Only available when DialAction is set to answer, connected, digits, or hangup.
`DialBLegTo`
Dial called number or SIP endpoint for B leg. Only available when DialAction is set to answer, connected, digits, or hangup.
`DialBLegHangupCauseName`
The reason for the B leg's hangup. Refer to our list of hangup causes and sources.
`DialBLegHangupCauseCode`
A unique integer code for the hangup cause. Refer to our list of hangup causes and sources.
`DialBLegHangupSource`
The entity that triggered the call hangup. Possible hangup sources are: Caller, Callee, Vobiz, API Request, Answer XML, Error, and Unknown
Refer to our list of hangup causes and sources.
`STIRVerification`
string
**For outbound calls:** Gives details about the attestation assigned to the call by Vobiz
**For inbound calls:** Gives details about the attestation received on the inbound call to your Vobiz phone number.
**Possible values:**
- **Verified** means the call is from a verified caller who has authorized access to the customer's caller ID, and hence should be treated with confidence. Verified is equivalent to attestation level A.
- **Not Verified** means that, for this call, either the caller is not verified, or it's uncertain whether they have access to the caller ID used, or both. Not Verified means the call received attestation level B or C.
- **Not Applicable** means STIR/SHAKEN doesn't apply to this call, as would be the case if a call is not addressed to a US number or if it's a cloud call (WebRTC or SIP).
Read more about STIR/SHAKEN here.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/dial/confirm-to-answer-call

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
return (
{/* Header Section */}
# Confirm to answer call
When multiple calls are fired, the first person to answer gets connected and the rest of the calls are dropped. To make sure that the call is answered by a person and not by voice mail, use the confirmKey and confirmSound attributes.
The example XML here requires the call recipient to input the digit 5 after answering the call to connect.
Vobiz requests the confirmSound URL using the POST HTTP method for a valid Play, Speak, or a Wait XML element. To play a message asking the recipient to input a DTMF tone to connect the call, return the second XML example.
{/* Example */}
## Example
### Response
```
.com/confirm_sound/" confirmKey="5">
12025551111
12025552222
12025553333
```
Return the following XML to play a message.
```
Enter the digit 5 to connect the call
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/dial/custom-caller-tone

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
return (
{/* Header Section */}
# Custom caller tone
When you make an outbound call and then connect that call to a different number using the Dial element, you can play a custom caller tone using the dialMusic attribute.
Vobiz requests the dialMusic URL using the POST HTTP method for a valid Play, Speak, or Wait XML element.
To play a message on a call while it's being connected, you should return the second XML example response.
{/* Example */}
## Example
### Response
```
.com/dial_music/">
12025551111
```
Return this XML to play the message
```
Your call is being connected
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/dial/dial-status-reporting

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
return (
{/* Header Section */}
# Dial status reporting
This examples uses an action URL in the Dial XML element. After the call ends, Vobiz reports back the status to this URL. You can control the flow of the call by returning valid Vobiz XML from the action URL and setting the redirect attribute to true.
In this example, Vobiz POSTs the status of the call to https://<yourdomain>.com/dial_status/ and expects valid XML since the redirect attribute is set to true.
{/* Example */}
## Example
### Response
```
.com/dial_status/" method="POST" redirect="true">
12025551111
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/dial/number

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
return (
{/* Header Section */}
# The Number Element
You can use the Number element to specify a phone number to dial.
You can use multiple Number elements within a Dial element to simultaneously call multiple numbers. The first call to pick up is connected to the current call and the rest are hung up.
Use the Number element to
- Forward an incoming call on a Vobiz number to a mobile or a landline number.
- Make an outbound call to an agent and then bridge the call to a client's number for call center use cases.
- Enable click to call, where you input a number on a web-based form and request a connection with another person.
**Note:** When dialing multiple numbers simultaneously, if confirmSound and confirmKey are specified for the Dial element, the number that confirms the key correctly is bridged and all others fail.
{/* Attributes */}
## Attributes
Attribute
Description
`sendDigits`
string
Tells the API to play DTMF tones when the call is answered. This is useful when dialing a phone number and an extension. The API dials the number, and when the automated system picks up, it sends DTMF tones to connect to the extension.
**Allowed values:** any digits and the w character. Each w character tells the Vobiz API to wait 0.5 seconds.
No default value.
`sendOnPreanswer`
boolean
If set to true, sendDigits is executed when the called party is in early media instead of answer state.
**Allowed values:** true, false
Defaults to false.
{/* Example */}
## Dialing extensions
This code dials the extension 2410 at the number 15671234567. The Number element describes the phone number and gives it the sendDigits attribute. To dial the extension a couple of seconds after the number is dialed, we add a few leading w characters, telling Vobiz to wait 0.5 seconds for each w.
### Response
```
sip:alice1234@registrar.vobiz.ai
15671234567
sip:john1234@registrar.vobiz.ai
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/dial/sequential-dialing

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
return (
{/* Header Section */}
# Sequential dialing
This example calls out to two phone numbers sequentially. The first call is made to a number with a timeout value of 20 seconds. If the call is not answered within that time, Vobiz will dial out to the second number.
{/* Example */}
## Example
### Response
```
.com/dial_action/">
12025551111
12025552222
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/dial/simultaneous-dialing

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
return (
{/* Header Section */}
# Simultaneous dialing
This example uses three User and Number elements to dial two SIP endpoints and a phone number at the same time. The first of these calls to answer will be connected to the caller, and the rest of the connection attempts will be canceled.
**Note: **In Simultaneous dialing, the maximum number of destinations (Endpoint or number) that can passed is 10
{/* Example */}
## Example
### Response
```
sip:alice1234@registrar.vobiz.ai
15671234567
sip:john1234@registrar.vobiz.ai
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/dial/user

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
return (
{/* Header Section */}
# The User Element
You can use the User element to specify a SIP endpoint (user) to dial.
You can use multiple User elements within a Dial element to simultaneously call multiple SIP endpoint users. The first user to answer is connected to the current call and the rest are hung up.
**Note:** When dialing multiple numbers simultaneously, if confirmSound and confirmKey are specified for the Dial element, the phone that confirms the key correctly is bridged and all others fail.
{/* Attributes */}
## Attributes
Attribute
Description
`sendDigits`
string
Tells the API to play DTMF tones when the call is answered. This is useful when dialing a phone number and an extension. Vobiz dials the number, and when the automated system picks up, it sends DTMF tones to connect to the extension.
**Allowed values:** any digits and the w character. Each w character tells the Vobiz API to wait 0.5 seconds.
No default value.
`sendOnPreanswer`
boolean
If set to true, sendDigits is executed when the called party is in early media instead of the answer state.
**Allowed values:** true, false
Defaults to false.
`sipHeaders`
string
List of SIP headers to send, separated by commas. For example, head1=val1,head2=val2,head3=val3,…,headN=valN. The SIP headers are always prefixed with X-PH-, and are always present for each HTTP request called by the dialed leg.
**Allowed values:** Only [A-Z], [a-z] and [0-9] characters are allowed for SIP header names and values to ensure you can encode them in a URL.
{/* Example */}
## Dialing extensions
This code calls the 2410 extension at sip:john1234@registrar.vobiz.ai. The User element describes the SIP endpoint and gives it the attribute sendDigits. To dial the extension a couple of seconds after the number is dialed, we add a few leading w characters, telling Vobiz to wait 0.5 seconds for each w.
### Response
```
sip:john1234@registrar.vobiz.ai
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/dtmf

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
return (
{/* Header Section */}
# The DTMF Element
You can use the DTMF element to send digits on a live call — for instance, to automate the process of navigating through an interactive voice response (IVR) tree.
If you set the async parameter to true, Vobiz will send digits in the background, so the call jumps to the next XML element when the first digit is sent. Use the character w to add a 0.5 second delay and the character W for a 1 second delay.
**Allowed values:** 1234567890*#wW
{/* Attributes */}
## Attributes
Attribute
Description
`async`
boolean
Proceed to next element after the first digit is sent.
**Allowed values:** true, false
Defaults to true.
{/* Example */}
## Send digits
This code sends the digits 1234 on the live call.
### Response
```
1234
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/gather

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'nesting-elements', title: 'Nesting Elements', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'action-params', title: 'Parameters sent to the action URL', level: 2 },
{ id: 'interim-params', title: 'Parameters sent to the interimSpeechResultsCallback URL', level: 2 },
];
return (
{/* Header Section */}
# The Gather Element
You can use the Gather XML element to collect user input through automatic speech recognition or DTMF "digit press" inputs.
When collecting speech as input, Vobiz transcribes and relays a user's speech to the specified action URL in real time.
When collecting input through digit press, Vobiz relays the digits entered to the specified action URL.
The Gather XML element supports simultaneous detection of both speech and digit press inputs.
{/* Nesting Elements */}
## Nesting elements
You can nest Speak XML (text-to-speech) and Play XML elements inside Gather XML to prompt users for inputs. This is useful for building interactive voice response (IVR) experiences.
{/* Attributes */}
## Attributes
Attribute
Description
`action`
(required)
String
Callback-retry configurable
The input is sent to a specific URL. See the "parameters sent to the action URL" table below for more information.
**Allowed values:** a fully qualified URL
`method`
String
The HTTP method to use when invoking the action URL.
**Allowed values:** GET, POST
Defaults to POST.
`inputType`
String
The type of input(s) you expect to receive.
**Allowed values:** dtmf, speech, dtmf speech
When set to dtmf speech, Vobiz listens for both speech and digit inputs. The input that's detected first is relayed to the action URL.
`executionTimeout`
integer
Maximum execution time, in seconds, for which input detection is carried out. If the user fails to provide input within the timeout period, the next element in the response will be processed. This duration is counted after nested Play/Speak elements have ended.
**Allowed values:** 5 to 60
Defaults to 15.
`digitEndTimeout`
String
Time, in seconds, allowed between consecutive digit inputs. If no new digit input is provided within the digitEndTimeout period, digits entered until then will be processed.
**Allowed values:** 2 to 10, or auto
Defaults to auto.
This attribute is applicable to input types dtmf and dtmf speech.
`speechEndTimeout`
String
Time, in seconds, that Vobiz waits for more speech once silence is detected before it stops speech recognition. At that point, a transcription of the collected speech is relayed to the action URL.
**Allowed values:** 2 to 10, or auto
Defaults to auto.
This attribute is applicable to input types speech and dtmf speech.
`finishOnKey`
String
A digit that the user can press to submit digits.
**Allowed values:** One and only one of 0–9, *, #, <empty string>, none
Defaults to #.
If set to <empty string> or none, input capture will end based on a timeout or the numDigits attribute.
This attribute is applicable to input types dtmf and dtmf speech.
`numDigits`
integer
The maximum number of digits to be processed in the current operation. Vobiz relays the digits to the action URL as soon as the maximum number of digits specified is collected.
**Allowed values:** 1 to 32
Default: 32
This attribute is applicable to input types dtmf and dtmf speech.
`speechModel`
String
The automatic speech recognition (ASR) model to use for transcribing the speech.
**Allowed values:** default, command_and_search, phone_call
Default: default
This attribute is applicable to input types speech and dtmf speech.
- **command_and_search:** Optimized for short queries such as voice commands and voice search.
- **phone_call:** Optimized for transcribing audio from a phone call where the quality of the audio is slightly inconsistent.
- **telephony:** telephony is an enhanced version of the phone_call model, optimized for audio typically originating from phone calls.
- **default:** Optimized for audio that is not one of the specific audio models such as long-form audio.
`hints`
String
A list of phrases to act as "hints" to the speech recognition model; these phrases can boost the probability that such words or phrases will be recognized. Phrases may be provided both as small groups of words or as single words.
**Allowed values:** a non-empty string of comma-separated phrases
**Limits:**
- Phrases per request: 500
- Characters per request: 10,000
- Characters per phrase: 100
This attribute is applicable to input types speech and dtmf speech.
`language`
String
Specifies the language Vobiz should recognize from the user.
**Allowed values:** See list of supported languages
Defaults to en-US.
This attribute is applicable to input types speech and dtmf speech.
`interimSpeechResultsCallback`
String
Callback-retry configurable
If interimSpeechResultsCallback URL is specified, requests to this URL are made in real-time as Vobiz recognizes speech.
See the "parameters sent to the interimSpeechResultsCallback URL" table below for more information.
**Allowed values:** a fully qualified URL
This attribute is applicable to input types speech and dtmf speech.
`interimSpeechResultsCallbackMethod`
String
The HTTP method to use when invoking the interimSpeechResultsCallback URL.
**Allowed values:** GET, POST
Defaults to POST.
This attribute is applicable to input types speech and dtmf speech.
`log`
boolean
If true, Vobiz will log digits or recognized speech from the caller. If false, logging will be disabled while processing the Gather element.
**Allowed values:** true, false
Defaults to true.
`redirect`
boolean
If true, redirect to action URL. If false, only request the URL and continue to the next element.
**Allowed values:** true, false
Defaults to true.
`profanityFilter`
boolean
If true, filters out profane words. Words filtered out are transcribed with their first letter and asterisks for the remaining characters (e.g. f***). The profanity filter operates on single words; it doesn't detect abusive or offensive speech that's a phrase or a combination of words.
**Allowed values:** true, false
Defaults to false.
This attribute is applicable to input types speech and dtmf speech.
{/* Parameters sent to action URL */}
## Parameters sent to the action URL
In addition to the standard action URL request parameters, these parameters are sent to the action URL specified.
Parameter
Description
`InputType`
The type of input detected.
**Allowed values:** dtmf, speech
`Digits`
The digits entered by the caller, excluding the finishOnKey input, if used. This parameter will be empty if inputType is speech.
`Speech`
The transcribed result of the caller's speech. This parameter will be empty if inputType is dtmf.
`SpeechConfidenceScore`
A confidence score between 0.0 and 1.0. The higher the confidence score, the more likely that the transcription is accurate.
`BilledAmount`
The total amount billed for speech input transcription.
{/* Parameters sent to interimSpeechResultsCallback URL */}
## Parameters sent to the interimSpeechResultsCallback URL
In addition to the standard callback URL request parameters, these parameters are sent to the interim speech results callback URL.
Parameter
Description
`StableSpeech`
The stable transcribed result of the user's speech.
`UnstableSpeech`
The newer unstable transcribed result of the user's speech. This is an interim result and may change as more speech is gathered from the caller.
`Stability`
An estimate of the likelihood that the recognizer will not change its guess about the interim result. Values range from 0.0 (completely unstable) to 1.0 (completely stable). This field only applies to unstable speech.
`SequenceNumber`
Contains a sequence number of the interim speech callback, to help with ordering incoming callback requests.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/gather/detecting-speech-inputs

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 },
];
return (
{/* Header Section */}
# Detecting speech inputs
Gather's automatic speech recognition (ASR) feature is ideal for accepting both unstructured and structured speech input from users. Structured inputs, in the form of keywords and commands, are suited for use cases that have a finite set of distinct operations for users to choose from, such as interactive voice response (IVR). Adding speech detection to DTMF-driven IVR menus can improve conversions by offering users an easier alternative to navigate through menus, as in this first example.
{/* Examples */}
## Examples
### Structured Input with DTMF and Speech
```
">
Press 1 or say New Appointment to schedule an appointment. Press 2 or say Cancel Appointment to cancel an existing appointment.
```
### Conversational AI with Speech Input
Real-time transcription of fuzzy inputs such as complete sentences, on the other hand, helps to build conversational AI-driven experiences.
```
">
Welcome to Mary's Hair Salon. How can I help you today?
```
An easy way to build AI conversational interfaces is by passing transcribed speech received through the Gather XML element to AI chatbot platforms such as Google Dialogflow for NLP-based intent extraction. Also read about how the Vobiz Speak XML element's Speech Synthesis Markup Language (SSML) engine can be used to make your bot's responses sound natural.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/gather/pricing-for-speech-recognition

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
];
return (
{/* Header Section */}
# Pricing for speech recognition
Speech recognition is charged based on the duration of speech analyzed in a Gather execution.
Charges are computed based on 15-second pulses, so if speech was recognized for 35 seconds, the account would be billed for 45 seconds (15 * 3) of speech.
Gather speech recognition charges are USD 0.02 per 15 seconds of execution.
Note that Vobiz charges only for speech input detection and not DTMF input detection. If you're using Gather with inputType set to dtmf, you won't be charged.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/gather/supported-languages

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
];
return (
{/* Header Section */}
# Supported languages
Name
Language Code
English (Australia)
`en-AU`
English (Canada)
`en-CA`
English (United Kingdom)
`en-GB`
English (Ireland)
`en-IE`
English (India)
`en-IN`
English (Philippines)
`en-PH`
English (Singapore)
`en-SG`
English (United States)
`en-US`
English (South Africa)
`en-ZA`
German (Germany)
`de-DE`
Spanish (Spain)
`es-ES`
Spanish (Mexico)
`es-MX`
Spanish (United States)
`es-US`
French (Canada)
`fr-CA`
French (France)
`fr-FR`
Italian (Italy)
`it-IT`
Japanese (Japan)
`ja-JP`
Korean (South Korea)
`ko-KR`
Dutch (Netherlands)
`nl-NL`
Portuguese (Brazil)
`pt-BR`
Portuguese (Portugal)
`pt-PT`
Russian (Russia)
`ru-RU`
Chinese, Mandarin (Simplified, China)
`zh (cmn-hans-cn)`
Chinese, Mandarin (Simplified, Hong Kong)
`zh-HK`
Chinese, Mandarin (Simplified, Taiwan)
`zh-TW (cmn-hans-tw)`
Chinese, Cantonese (Traditional, Hong Kong)
`yue-Hant-HK`
Afrikaans (South Africa)
`af-ZA`
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/hangup

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
];
return (
{/* Header Section */}
# The Hangup Element
You can use the Hangup element to end a call if you don't want to answer an incoming call on your Vobiz number. The application attached to the Vobiz number must return the Hangup XML element along with a reason attribute to end the call.
{/* Attributes */}
## Attributes
The Hangup element supports these attributes. You can modify the behavior of each attribute using the allowed values.
Attribute
Description
`reason`
string
Specifies the reason for the hangup.
**Allowed values:** rejected, busy
`schedule`
integer
Used to schedule a call hangup. Should be followed by an element such as Speak; if not, the call will be hung up immediately.
**Allowed values:** integer > 0 (in seconds)
**Note:**
- When the Hangup XML element is the first element in an Answer XML element, the call is hung up with reason rejected by default if the reason attribute is not specified.
- When Hangup XML is not the first element or if the call is already answered, the call is hung up with reason Normal Hangup if the reason attribute is not specified.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/hangup/hang-up-after-a-minute

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
return (
{/* Header Section */}
# Hang up call after a minute
This example shows how to schedule a hangup for a call after a minute while playing a message on the call.
{/* Example */}
## Example
```
This call will be hung up after a minute
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/play

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
];
return (
{/* Header Section */}
# The Play Element
You can use the Play element to play an audio file from a remote URL to a caller. Vobiz supports MP3 and WAV audio file formats.
{/* Attributes */}
## Attributes
Attribute
Description
`loop`
integer
The number of times to play the audio file repeatedly. If you set the value to 0, the file will play indefinitely.
**Allowed values:** integer >= 0
Defaults to 1.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/play/play-music

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 },
];
return (
{/* Header Section */}
# Play music
This example plays the audio file Trumpet.mp3 to the caller.
{/* Example */}
## Example Request
```
https://audio.com/example.mp3
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/preanswer

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'nesting-rules', title: 'Nesting Rules', level: 2 },
];
return (
{/* Header Section */}
# The PreAnswer Element
The PreAnswer element answers an incoming call in early media mode. This is useful when you want to play custom caller tunes or to speak text while the call is still in an unanswered state.
**Note:** Not all phone numbers support this feature. Browser SDK doesn't support early media (PreAnswer) as it's not a part of the WebRTC specifications.
{/* Attributes */}
## Attributes
Attribute
Description
The PreAnswer element does not have any attributes.
{/* Nesting Rules */}
## Nesting rules
You can nest Speak, Play, and Wait elements within the PreAnswer element.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/preanswer/notify-callers

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 },
];
return (
{/* Header Section */}
# Notify callers
This example notifies the caller that the cost of the current call is $2 a minute.
{/* Example */}
## Example Request
```
This call will cost you $2 a minute.
Hey, thanks for dropping by.
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/record

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'action-params', title: 'Parameters sent to the action URL', level: 2 },
{ id: 'callback-params', title: 'Parameters sent to the callback URL', level: 2 },
{ id: 'transcription-params', title: 'Parameters sent to the transcription URL', level: 2 },
];
return (
{/* Header Section */}
# The Record Element
The Record element records a call or conference and posts the URL of the recording to an action URL.
{/* Attributes */}
## Attributes
Attribute
Description
`action`
string
Callback-retry configurable
A URL to which the parameters are sent. The parameters sent to the action URL are described below. This is a required attribute.
**Allowed values:** A fully qualified URL
`method`
string
Callback-retry configurable
The method used to send the result of the recording to the action URL.
**Allowed values:** GET, POST
Defaults to POST.
`fileFormat`
string
Specifies the file format of the recording.
**Allowed values:** mp3, wav
Defaults to mp3.
`redirect`
boolean
If set to true, the action URL will not be fetched; instead, the XML response will be retrieved and executed after the recording is done. If set to false, the action URL will be fetched and the response will be executed without even retrieving the XML response.
**Allowed values:** true, false
Defaults to false.
`timeout`
integer
The maximum time in seconds to record. When this time is reached, the recording ends. The timeout does not set a duration limit on the recording (no time limit is set). For recordings that are ended due to a timeout, the RecordingEndReason parameter sent to the action URL has a value of RecordingTimeout.
**Allowed values:** integer > 0
Defaults to 60.
`maxLength`
integer
The maximum length of the recording in seconds. Once this time is reached, the recording ends. For recordings that end due to the maxLength limit, the RecordingEndReason sent to the action URL has a value of maxLength.
**Allowed values:** integer > 0
Defaults to 60.
`playBeep`
boolean
If set to true, a beep will be played before the recording begins.
**Allowed values:** true, false
Defaults to true.
`finishOnKey`
string
When this key is pressed, the recording will stop. For recordings that end due to this attribute, the RecordingEndReason sent to the action URL has a value of FinishedOnKey.
**Allowed values:** Any digit, #, *
Defaults to 1234567890*#.
`recordSession`
boolean
If set to true, the entire session will be recorded, including multiple plays or speak elements. The recording will end when the call is hung up. For recordings that end due to recordSession being set to true, the RecordingEndReason sent to the action URL has a value of HungUp.
**Allowed values:** true, false
Defaults to false.
`startOnDialAnswer`
boolean
If set to true, the recording will start when the call is answered. This is used for outbound calls, where the record element is embedded in the Dial element.
**Allowed values:** true, false
Defaults to false.
`transcriptionType`
string
Specifies the type of transcription service to use.
**Allowed values:** auto, hybrid
Defaults to auto.
Note: Transcription is available at an additional cost. Please refer to the pricing page for more details.
- **auto:** The recording is transcribed using the default Vobiz transcription service.
- **hybrid:** The recording will be transcribed using the Vobiz transcription service for the most common languages and a third-party provider for all other languages.
`transcriptionUrl`
string
Callback-retry configurable
A URL to which the transcription is sent.
**Allowed values:** A fully qualified URL
`transcriptionMethod`
string
Callback-retry configurable
Specifies the HTTP method to use when requesting the transcriptionUrl.
**Allowed values:** GET, POST
Defaults to POST.
`callbackUrl`
string
Callback-retry configurable
A URL to which parameters are sent when the recording ends. This is similar to the action URL, but the recording URL will be ready by the time the callback is made. The parameters sent to the callback URL are the same as those sent to the action URL.
**Allowed values:** A fully qualified URL
`callbackMethod`
string
Callback-retry configurable
Specifies the HTTP method to use when requesting the callbackUrl.
**Allowed values:** GET, POST
Defaults to POST.
{/* Parameters sent to the action URL */}
## Parameters sent to the action URL
Parameter
Description
`RecordUrl`
string
The URL of the recording file. When you receive this parameter, you may need to wait a few seconds for the file to be ready for download. Alternatively, you can use the callbackUrl attribute to receive a notification once the file is ready.
`RecordingDuration`
integer
The duration of the recording in seconds.
`RecordingDurationMs`
integer
The duration of the recording in milliseconds.
`RecordingStartMs`
integer
The timestamp when the recording started, in milliseconds.
`RecordingEndMs`
integer
The timestamp when the recording ended, in milliseconds.
`RecordingID`
string
A unique identifier for the recording.
`RecordingEndReason`
string
The reason the recording ended. Possible values are:
- **RecordingTimeout:** Recording ended due to timeout
- **maxLength:** Recording reached the maxLength limit
- **FinishedOnKey:** Recording ended when the finishOnKey was pressed
- **HungUp:** Recording ended when the call was hung up
{/* Parameters sent to the callback URL */}
## Parameters sent to the callback URL
The parameters sent to the callback URL are the same as those sent to the action URL.
{/* Parameters sent to the transcription URL */}
## Parameters sent to the transcription URL
Parameter
Description
`transcription`
string
The text of the transcription.
`transcription_id`
string
A unique identifier for the transcription.
`transcription_url`
string
The URL of the transcription file.
`recording_id`
string
A unique identifier for the recording.
{/* Previous/Next Page Navigation */}
{/*  */}
);
}

---

# Page: /xml/record/record-a-voicemail

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
const xmlCode = `
Please leave a message at the beep. Press the star key when done.
Recording not received.
`;
return (
{/* Header Section */}
# Record a voicemail
This example shows how to record a voicemail message. The recording will stop when the caller presses the star key or after 30 seconds, whichever comes first.
{/* Example */}
## Example
In this example, the caller hears a message asking them to leave a voicemail. After the beep, the recording begins. The recording will stop when the caller presses the star key (*) or after 30 seconds. If no recording is received, the caller will hear "Recording not received."
### XML Response
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/record/stream-with-record

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'stream-with-record-xml', title: 'Stream with Record XML', level: 2 },
{ id: 'record-event-callback', title: 'Record Event Callback', level: 2 },
{ id: 'stream-with-record-callback-xml', title: 'Stream with Record & Callback URL XML', level: 2 },
{ id: 'record-stop-event-callback', title: 'RecordStop Event Callback', level: 2 },
];
return (
# Stream with Record
You can use the `<Record>` and `<Stream>` elements together to simultaneously record a call and stream its audio to a WebSocket in real-time. This is useful for applications that require both persistent storage of the call audio and live processing, such as real-time transcription and analysis.
## Stream with Record XML
```
https://www.vobix.com/test/62801/play.wav
ws://sipp.voice.vobizdev.com:19092/ws
https://www.vobix.com/test/62801/play.wav
```
## Record Event Callback Parameters
The Record event will go to the callback URL once recording starts on the call. The recording will be accessible via media.vobiz.ai after the recording is complete.
Parameter
Description
{[
{ name: 'Digits', desc: 'Digits pressed during the call.' },
{ name: 'From', desc: 'The calling party number.' },
{ name: 'RecordingID', desc: 'The unique ID for the recording.' },
{ name: 'RecordFile', desc: 'The URL of the recorded file.' },
{ name: 'RecordingEndMs', desc: 'The timestamp when the recording ended.' },
{ name: 'BillRate', desc: 'The billing rate for the call.' },
{ name: 'To', desc: 'The called party number.' },
{ name: 'RecordingDurationMs', desc: 'The duration of the recording in milliseconds.' },
{ name: 'CallUUID', desc: 'The unique ID for the call.' },
{ name: 'ALegRequestUUID', desc: 'The request UUID for the A leg of the call.' },
{ name: 'SessionStart', desc: 'The timestamp when the session started.' },
{ name: 'Direction', desc: 'The direction of the call (inbound or outbound).' },
{ name: 'RecordUrl', desc: 'The URL of the recorded file.' },
{ name: 'RecordingDuration', desc: 'The duration of the recording in seconds.' },
{ name: 'ALegUUID', desc: 'The unique ID for the A leg of the call.' },
{ name: 'CallStatus', desc: 'The status of the call.' },
{ name: 'ParentAuthID', desc: 'The parent authentication ID.' },
{ name: 'RequestUUID', desc: 'The unique ID for the request.' },
{ name: 'Event', desc: 'The event type (Record).' },
{ name: 'RecordingStartMs', desc: 'The timestamp when the recording started.' },
].map((param) => (
`{param.name}`
{param.desc}
))}
## Stream with Record & Callback URL XML
```
https://www.vobix.com/test/62801/play.wav
ws://sipp.voice.vobizdev.com:19092/ws
https://www.vobix.com/test/62801/play.wav
```
## RecordStop Event Callback Parameters
A RecordStop event will be posted to the callbackUrl when the recording is stopped.
Parameter
Description
{[
{ name: 'From', desc: 'The calling party number.' },
{ name: 'RecordingID', desc: 'The unique ID for the recording.' },
{ name: 'RecordFile', desc: 'The URL of the recorded file.' },
{ name: 'RecordingEndMs', desc: 'The timestamp when the recording ended.' },
{ name: 'BillRate', desc: 'The billing rate for the call.' },
{ name: 'To', desc: 'The called party number.' },
{ name: 'RecordingDurationMs', desc: 'The duration of the recording in milliseconds.' },
{ name: 'CallUUID', desc: 'The unique ID for the call.' },
{ name: 'ALegRequestUUID', desc: 'The request UUID for the A leg of the call.' },
{ name: 'SessionStart', desc: 'The timestamp when the session started.' },
{ name: 'Direction', desc: 'The direction of the call (inbound or outbound).' },
{ name: 'RecordUrl', desc: 'The URL of the recorded file.' },
{ name: 'RecordingDuration', desc: 'The duration of the recording in seconds.' },
{ name: 'ALegUUID', desc: 'The unique ID for the A leg of the call.' },
{ name: 'CallStatus', desc: 'The status of the call.' },
{ name: 'ParentAuthID', desc: 'The parent authentication ID.' },
{ name: 'RequestUUID', desc: 'The unique ID for the request.' },
{ name: 'Event', desc: 'The event type (RecordStop).' },
{ name: 'RecordingStartMs', desc: 'The timestamp when the recording started.' },
].map((param) => (
`{param.name}`
{param.desc}
))}
);
}

---

# Page: /xml/redirect

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'redirect-params', title: 'Parameters sent in the redirect request', level: 2 },
];
return (
{/* Header Section */}
# The Redirect Element
You can use the Redirect element to transfer control of a call to a different URL, which then starts processing the new XML response. Any elements after <Redirect> are not processed.
{/* Attributes */}
## Attributes
Attribute
Description
`method`
string
Callback-retry configurable
Specifies the HTTP request mode to obtain the Redirect URL.
**Allowed values:** GET, POST
Defaults to POST.
{/* Parameters sent in the redirect request */}
## Parameters sent in the redirect request
Parameter
Description
`From`
string
The phone number of the party that initiated the call, along with the country code. If the call is inbound, then this is the caller's caller ID. If the call is outbound — initiated via a request to the API — then this is the phone number you specify as the caller ID.
`To`
string
The phone number of the called party, with the country code. If the call is inbound, then this is your incoming phone number. If the call is outbound, then this is the phone number you provided to call.
`Event`
string
The string Redirect.
`CallUUID`
string
A unique identifier for the call.
`CallerName`
string
For a SIP call, this is the name of the caller. For a PSTN call, this is the caller ID.
`Direction`
string
Indicates the direction of the call. In most cases this will be inbound, and the call would be in a ringing state. If you're using the Call API, the direction will be outbound, and the call will be in an answered state.
`CallStatus`
string
Indicates the status of the call. The value may be set to ringing, in-progress, or completed. If the call is hung up, CallStatus is set to completed for inbound calls and to completed, busy, failed, timeout, or no-answer for outbound calls.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/redirect/transfer-a-call

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example Request', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'connect-number', title: 'Connect to a different number', level: 2 },
];
return (
{/* Header Section */}
# Transfer a call
In this example, we have a Redirect element after a Speak element. When the Speak element finishes, the Redirect element executes, and Vobiz processes the call based on the XML returned from the Redirect element.
{/* Example Request */}
## Example Request
```
Please wait while you call is being transferred.
https://.com/redirect/
```
{/* Response */}
## Response
To connect the incoming call to a different number, you should return the section example's XML from the Redirect URL.
```
12025551111
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/request

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'voice-calls', title: 'Voice calls', level: 2 },
];
return (
{/* Header Section */}
# XML request
When Vobiz makes a synchronous HTTP request to your application, the API expects an XML document in response. Vobiz sends a few parameters with the HTTP request that your application can act upon before responding.
**Note:** The maximum allowed size of the XML document in response to an HTTP request from Vobiz to your application is 100 Kb.
{/* Voice Calls */}
## Voice calls
### Parameters Vobiz sends for voice calls
Parameter
Description
`CallUUID`
A unique identifier for this call.
`From`
The phone number of the party that initiated the call, including the country code.
If the call is inbound, then this parameter is the caller's caller ID. If the call is outbound — initiated via a request to the API — then this is the phone number you specify as the caller ID.
`To`
The phone number of the called party, including the country code.
If the call is inbound, then it's your incoming phone number. If the call is outbound, then it's the destination phone number you provided.
`ForwardedFrom`
Set only when a received call is a forwarded call. Its value depends on the caller's carrier. Not all carriers pass this information.
`CallStatus`
Indicates the status of the call.
The value is set to either ringing, in-progress, or completed. If the call is hung up, the CallStatus will be set to completed for inbound calls and to completed, busy, failed, timeout, or no-answer for outbound calls.
`Direction`
Indicates the direction of the call.
In most cases this will be inbound, and the call will be in a ringing state. If you're using the Call API, the direction will be outbound and the call will be in an answered state.
`ALegUUID`
Contains a unique identifier that identifies the first leg of an outbound call.
If the call direction is inbound, this parameter will not be present.
`ALegRequestUUID`
Contains a unique request identifier that Vobiz returns for an API request during an outbound call.
If the call direction is inbound, this parameter will not be present.
`HangupCause`
Contains the standard telephony hangup cause of a call (inbound and outbound).
If a call is not hung up, this parameter will not be present.
`Duration`
Contains the duration of the call in seconds.
If the call is not hung up, this parameter will not be present.
`BillDuration`
Contains the billed duration of the call in seconds.
If the call is not hung up, this parameter will not be present.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/request/call-status

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'callstatus-values', title: 'List of CallStatus values', level: 2 },
];
return (
{/* Header Section */}
# Call status
Vobiz sends a call status to request URLs under the CallStatus key. Your application can make decisions about how to process a call based on this status.
Vobiz will send one of these values under the CallStatus parameter:
{/* CallStatus Values */}
## List of CallStatus values
Value
Description
`in-progress`
string
The call was answered and is currently in progress. Calls under this status can be explicitly terminated using the Hangup API.
`completed`
string
The call was completed. It was either terminated using the Hangup API or ended by one of the parties in the call.
`ringing`
string
The call is currently ringing. This status is sent to the Ring URL.
`no-answer`
string
The call wasn't answered by the recipient. Your application must have the logic to parse this parameter and take actions based on it.
`busy`
string
The recipient is busy on another call. You may retry after some time.
`cancel`
string
The call was canceled by the caller
`timeout`
string
There was a timeout while connecting your call, caused by either an issue with one of the terminating carriers or network lag in our system.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/request/event

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'event-values', title: 'List of Event values', level: 2 },
];
return (
{/* Header Section */}
# Event
Vobiz generates events when the state of a call changes to let the application know about the progress of the call.
Vobiz will send one of these values under the Event parameter:
{/* Event Values */}
## List of Event values
Value
Description
`StartApp`
The call was answered and is currently in progress. Calls with this status can be explicitly terminated using the Hangup API.
`Transfer`
The call was transferred using the Transfer API. This event is sent to the target URL of the XML you return from the transfer URL.
`Redirect`
The call was redirected using the Redirect XML element.
`MachineDetection`
Vobiz generates this event when the machine_detection parameter is used in the Outbound Call API request. The event is sent to the machine_detection URL.
### Example Response
```
true
```
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/request/sip-headers

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'outbound-calls', title: 'Outbound calls', level: 2 },
{ id: 'inbound-calls', title: 'Inbound calls', level: 2 },
];
return (
{/* Header Section */}
# SIP headers
If you're using a SIP endpoint and you've configured your SIP phone to send custom SIP headers starting with X-PH-, Vobiz will send these SIP headers with the HTTP request.
{/* Outbound Calls */}
## Outbound calls
For outbound calls, you can set custom SIP headers while :
- Making an outbound call
- Using the nested Number element of the Dial element
- Using the nested User element of the Dial element
{/* Inbound Calls */}
## Inbound calls
For inbound calls, you need a SIP phone that allows custom SIP headers. If you have one, SIP headers that start with X-PH- will sent as HTTP requests.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/response

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'nesting', title: 'Nesting Rules', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 },
];
return (
{/* Header Section */}
# The <Response> Element
The root element for all Vobiz XML documents. Every XML response must be wrapped in a single{' '} `Response` element.
### Purpose
The `Response` element acts as the container for all XML verb elements that control call behavior. It tells Vobiz that the XML document contains valid call instructions and marks the beginning and end of your call flow logic.
{/* Attributes */}
## Attributes
Attribute
Type
Required
Description
The Response element has no attributes.
{/* Nesting Rules */}
## Nesting Rules
### Allowed Child Elements
The `Response` element can contain the following verb elements:
{[
'Speak',
'Play',
'Dial',
'Record',
'Gather',
'Hangup',
'Redirect',
'Wait',
'Conference',
'DTMF',
'PreAnswer',
'AudioStream',
'MultiPartyCall'
].map((element) => (
→
`<{element}>`
))}
### Parent Elements
The `Response` element has no parent - it is always the root element.
**Important:** Every XML document must have exactly one{' '} `Response` element. Multiple Response elements or missing Response elements will result in an XML parsing error.
{/* Examples */}
## Examples
### Basic Usage
```
Hello! This is a basic XML response.
```
### Multiple Actions
```
Thank you for calling Vobiz support.
https://yourcdn.com/hold-music.mp3
+14155551234
```
Verb elements are executed in the order they appear. In this example, Vobiz will first speak the message, then play the hold music, and finally dial the number.
### IVR Flow
```
Press 1 for sales, press 2 for support.
We didn't receive your input. Goodbye!
```
This response collects one digit from the user. If no input is received within 10 seconds, it speaks a goodbye message and hangs up.
### Empty Response
```
```
An empty `Response` element is valid but doesn't perform any actions. The call will simply continue without any instructions. Typically, you'd use this for call events where no action is needed.
{/* Best Practices */}
## Best Practices
### Always Include XML Declaration
Start your XML documents with{' '} `<?xml version="1.0" encoding="UTF-8"?>` to ensure proper parsing and character encoding.
### Validate Your XML
Use an XML validator or linter during development to catch syntax errors before deploying to production. Malformed XML will cause call failures.
### Set Proper Content-Type
When your application responds to Vobiz webhooks, set the HTTP{' '} `Content-Type` header to{' '} `application/xml` or{' '} `text/xml`.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/speak

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
{ id: 'supported-voices', title: 'Supported voices and languages', level: 2 },
];
return (
{/* Header Section */}
# The Speak Element
You can use the Speak element to read out text as speech to the caller. It's useful for communicating dynamic text that cannot be prerecorded.
{/* Attributes */}
## Attributes
Attribute
Description
`voice`
string
The tone to be used for reading out the text.
**Allowed values:** WOMAN, MAN
Defaults to WOMAN.
`language`
string
Language used to read out the text.
**Allowed values:** See the table "Supported voices and languages" below.
Defaults to en-US.
`loop`
integer
Specifies number of times to speak out the text. If value set to 0, speaks indefinitely.
**Allowed values:** integer >= 0 (0 indicates a continuous loop)
Defaults to 1.
{/* Supported voices and languages */}
## Supported voices and languages
Language
Woman
Man
Danish
value: da-DK
yes
no
Dutch
value: nl-NL
yes
yes
English — Australian
value: en-AU
yes
yes
English — British
value: en-GB
yes
yes
English — USA
value: en-US
yes
yes
French
value: fr-FR
yes
yes
French — Canadian
value: fr-CA
yes
no
German
value: de-DE
yes
yes
Italian
value: it-IT
yes
yes
Polish
value: pl-PL
yes
yes
Portuguese
value: pt-PT
no
yes
Portuguese — Brazilian
value: pt-BR
yes
yes
Russian
value: ru-RU
yes
no
Spanish
value: es-ES
yes
yes
Spanish — USA
value: es-US
yes
yes
Swedish
value: sv-SE
yes
no
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/speak/play-a-message

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
const xmlCode = `
Vobiz - Simple, AI-first telephony for voice agents.
`;
return (
{/* Header Section */}
# Play a message
In this first example, when a call is directed to this example XML document, the caller will hear "Vobiz - Simple, AI-first telephony for voice agents" spoken once.
{/* Example */}
## Example
### Response
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/speak/play-in-a-loop

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
const xmlCode = `
Wow
`;
return (
{/* Header Section */}
# Play in a loop
This second XML example tells Vobiz to say "Wow" three times.
{/* Example */}
## Example
### Response
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/speak/ssml

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 },
];
const xmlExample1 = `
Hello and welcome to the Vobiz text-to-speech engine.   We're now testing the SSML feature.   `; const xmlExample2 = `    Please press 1 to proceed.   We're now testing the SSML feature.    `; return (  {/* Header Section */}  # SSML  Speech Synthesis Markup Language (SSML) provides a standard way to mark up text for the generation of synthesized speech. It supports 27 languages and more than 40 voices, and allows developers to control pronunciation, pitch, and volume.
For more information on SSML, see Getting Started with SSML.
Speak elements with SSML can be nested inside Gather XML element tags.
{/* Examples */}
## Examples
### Basic SSML Example
### SSML with Gather
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/wait

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'attributes', title: 'Attributes', level: 2 },
];
return (
{/* Header Section */}
# The Wait Element
The Wait element waits silently for a specified number of seconds. If <Wait> is the first element in a XML document, Vobiz will wait the specified number of seconds before picking up the call.
{/* Attributes */}
## Attributes
Attribute
Description
`length`
integer
Time to wait in seconds
**Allowed values:** integer greater than 0
Defaults to 1.
`silence`
boolean
If silence is set to true, if no voice or sound is detected for minSilence milliseconds, Vobiz will end the wait and continue to the next element in the XML code immediately (effectively cutting the wait for length seconds short).
If silence is set to false, Vobiz will wait for the full period of length seconds, regardless of the presence of sound or voice or the value of minSilence.
**Allowed values:** true or false
Defaults to false.
`minSilence`
integer
The minimum length in milliseconds of silence that needs to be present to qualify as silence.
Only used when silence is set to true. Note that the duration of length needs to be greater than the duration of minSilence for this attribute to work as expected.
**Allowed values:** integer > 0
Defaults to 2,000.
`beep`
boolean
Used to detect a voicemail machine, so an application can leave voicemail messages. Only used when silence and minSilence are false.
**Allowed values:** true, false
Defaults to false.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/wait/basic-wait

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
const xmlCode = `
I will wait for seven seconds starting now.
I just waited seven seconds.
`;
return (
{/* Header Section */}
# Basic wait
This first example demonstrates how to wait for seven seconds between two lines of speech.
{/* Example */}
## Example
### Response
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/wait/beep-detection

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
const xmlCode = `
Hello
`;
return (
{/* Header Section */}
# Beep detection
You can use the Wait element to aid leaving voice mails on answering machines by adding an extra parameter called beep and setting it to true.
{/* Example */}
## Example
### Response
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/wait/delayed-call-answer

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
const xmlCode = `
Hello
`;
return (
{/* Header Section */}
# Delayed call answer
This example demonstrates how to wait for 10 seconds before accepting a call.
{/* Example */}
## Example
### Response
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /xml/wait/machine-detection

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'example', title: 'Example', level: 2 },
];
const xmlCode = `
Hello, welcome to the jungle.
`;
return (
{/* Header Section */}
# Machine detection
You can use the silence parameter in conjunction with the machine_detection feature of the Call API to enable your XML to detect whether a call is answered by voice mail. When silence is set to true, as soon as the voice mail finishes speaking, and there is silence for minSilence milliseconds, the next element in the XML is processed, without waiting for the whole period of length seconds to pass.
{/* Example */}
## Example
### Response
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /call

'use client';
const router = useRouter();
useEffect(() => {
router.replace('/call/overview');
}, [router]);
return null;
}

---

# Page: /cdr

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'http-request', title: 'HTTP Request', level: 2 },
{ id: 'query-parameters', title: 'Query Parameters', level: 2 },
{ id: 'response', title: 'Response', level: 2 },
{ id: 'examples', title: 'Examples', level: 2 }
];
return (
# Call Detail Records (CDR)
Retrieve detailed call logs and usage data for your account.
The Call Detail Records (CDR) API endpoint allows you to fetch comprehensive call logs for your account. This includes information about call participants, duration, status, costs, timestamps, and more. CDR data is essential for billing reconciliation, usage analytics, and compliance reporting.
**Use Cases:** CDRs are commonly used for billing verification, traffic analysis, fraud detection, and generating usage reports. You can filter records by date range and paginate through large datasets efficiently.
## HTTP Request
GET
https://api.vobiz.ai/api/v1/account/{`{ACCOUNT_ID}`}/cdr
Authentication Required:
- • **X-Auth-ID:** Your account ID (e.g., MA_BN2MZ1VV)
- • **X-Auth-Token:** Your account Auth Token
- • **Content-Type:** application/json
## Query Parameters
## Response
A successful request returns a `200 OK` status with a JSON body containing an array of call objects.
```
{
"data": [
{
"call_id": "abc123-def456-ghi789",
"from_number": "+912271264217",
"to_number": "+919876543210",
"direction": "outbound",
"duration": 125,
"status": "completed",
"start_time": "2026-01-23T10:30:00Z",
"end_time": "2026-01-23T10:32:05Z",
"cost": 0.05,
"currency": "USD",
"trunk_id": "e3e55a78-1234-5678-90ab-cdef12345678",
"caller_id": "+912271264217",
"hangup_cause": "NORMAL_CLEARING"
},
{
"call_id": "xyz789-uvw456-rst123",
"from_number": "+919876543210",
"to_number": "+912271264217",
"direction": "inbound",
"duration": 45,
"status": "completed",
"start_time": "2026-01-23T09:15:00Z",
"end_time": "2026-01-23T09:15:45Z",
"cost": 0.02,
"currency": "USD",
"trunk_id": "e3e55a78-1234-5678-90ab-cdef12345678",
"caller_id": "+919876543210",
"hangup_cause": "NORMAL_CLEARING"
}
],
"pagination": {
"current_page": 1,
"per_page": 20,
"total_records": 150,
"total_pages": 8
}
}
```
#### Response Fields
- • `call_id` - Unique identifier for the call
- • `from_number / to_number` - Call participants
- • `duration` - Length of the call in seconds
- • `status` - Call status (e.g., "completed", "no-answer", "busy", "failed")
- • `cost` - Price of the call (if applicable)
- • `direction` - "inbound" or "outbound"
- • `hangup_cause` - Reason for call termination
## Examples
#### cURL - Fetch CDR for Date Range
```
curl -X GET "https://api.vobiz.ai/api/v1/account/{ACCOUNT_ID}/cdr?start_date=2025-12-31&end_date=2026-01-23&per_page=20&page=1" \\
-H "X-Auth-ID: {ACCOUNT_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}" \\
-H "Content-Type: application/json"
```
#### Generic Template (Use Your Own Values)
```
curl -X GET "https://api.vobiz.ai/api/v1/account/{ACCOUNT_ID}/cdr?start_date={YYYY-MM-DD}&end_date={YYYY-MM-DD}&per_page={LIMIT}&page={PAGE_NUMBER}" \\
-H "X-Auth-ID: {ACCOUNT_ID}" \\
-H "X-Auth-Token: {AUTH_TOKEN}" \\
-H "Content-Type: application/json"
```
#### Parameter Quick Reference
Parameter
Example
Description
`start_date`
2025-12-31
Beginning of search period (YYYY-MM-DD)
`end_date`
2026-01-23
End of search period
`per_page`
20
Records per request (pagination)
`page`
1
Page number to view
**Quick Tips:**
- • **Date Format:** Always use YYYY-MM-DD format for dates
- • **Pagination:** Use `per_page` and `page` for large datasets
- • **Date Range:** Limit your date range to avoid timeouts on large datasets
**Common Use Cases:**
- • **Billing Reconciliation:** Verify call costs against invoices
- • **Traffic Analysis:** Analyze call patterns and peak usage times
- • **Fraud Detection:** Monitor for unusual calling patterns
- • **Compliance Reporting:** Generate call logs for regulatory requirements
- • **Usage Reports:** Create detailed usage reports for customers
);
}

---

# Page: /integrations/livekit

const tableOfContents = [
{ id: 'overview', title: 'Overview', level: 2 },
{ id: 'prerequisites', title: 'Prerequisites', level: 2 },
{ id: 'part-1', title: 'Part 1: Vobiz Setup', level: 2 },
{ id: 'part-2', title: 'Part 2: LiveKit Setup', level: 2 },
{ id: 'part-3', title: 'Part 3: Connect LiveKit to Vobiz', level: 2 },
{ id: 'part-4', title: 'Part 4: Make Outbound Calls', level: 2 },
{ id: 'part-5', title: 'Part 5: Configure Inbound Calling', level: 2 },
{ id: 'part-6', title: 'Part 6: SIP Call Transfer', level: 2 },
{ id: 'troubleshooting', title: 'Troubleshooting', level: 2 },
{ id: 'quick-reference', title: 'Quick Reference', level: 2 },
{ id: 'resources', title: 'Additional Resources', level: 2 }
];
return (
{/* Header */}
# LiveKit + Vobiz Integration Guide
Connect your LiveKit AI voice agents to Vobiz SIP infrastructure for phone calling capabilities.
{/* Overview */}
## Overview
This guide shows how to integrate LiveKit with Vobiz to enable:
- **Outbound calling** - AI agents can call any phone number
- **Inbound calling** - AI agents can answer calls to your Vobiz numbers
Integration flow:
```
Outbound: Your App → LiveKit → Vobiz → Phone Network
Inbound:  Phone Network → Vobiz → LiveKit → AI Agent
```
{/* Prerequisites */}
## Prerequisites
Before starting:
✅
**Vobiz Account** with active balance → [Create account](https://vobiz.ai)
✅
**LiveKit Account** with project → [Sign up](https://cloud.livekit.io)
✅
**LiveKit AI Agent** built → [LiveKit Agents docs](https://docs.livekit.io/agents)
{/* Part 1: Vobiz Setup */}
## Part 1: Vobiz Setup
{/* Create SIP Trunk */}
### Create SIP Trunk
Create a SIP trunk in Vobiz to handle voice traffic.
**See:** [Vobiz SIP Trunks Documentation](/trunks)
⚠️ Save these values from the response:
- `sip_domain` (e.g., `5f3a607b.sip.vobiz.ai`)
- `username`
- `password`
You'll need them for LiveKit configuration.
{/* Get Phone Number */}
### Get Phone Number
Purchase a phone number for outbound caller ID or inbound calls.
**See:** [Vobiz Phone Numbers Documentation](/account-phone-number)
{/* Part 2: LiveKit Setup */}
## Part 2: LiveKit Setup
{/* Get LiveKit Credentials */}
### Get LiveKit Credentials
- Go to [LiveKit Cloud Dashboard](https://cloud.livekit.io)
- Select your project
- Navigate to **Settings** → **Keys**
- Copy these values:
Credential
Where to Find
LIVEKIT_URL
Settings → Project URL
LIVEKIT_API_KEY
Settings → Keys → API Key
LIVEKIT_API_SECRET
Settings → Keys → Secret Key
```
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxxxxxxx
LIVEKIT_API_SECRET=secretxxxxxxxxxx
```
{/* Part 3: Connect LiveKit to Vobiz */}
## Part 3: Connect LiveKit to Vobiz (Outbound)
{/* Initialize LiveKit API Client */}
### Initialize LiveKit API Client
**Example Code:** For a complete example of Outbound Caller, check the [LiveKit Vobiz Outbound Repository](https://github.com/vobiz-ai/LiveKit-Vobiz-Outbound).
```
from livekit import api as livekit_api
lk = livekit_api.LiveKitAPI(
url="YOUR_LIVEKIT_URL",
api_key="YOUR_LIVEKIT_API_KEY",
api_secret="YOUR_LIVEKIT_API_SECRET"
)
```
{/* Create Outbound Trunk */}
### Create Outbound Trunk
Connect LiveKit to your Vobiz SIP trunk:
```
trunk = await lk.sip.create_sip_outbound_trunk(
livekit_api.CreateSIPOutboundTrunkRequest(
trunk=livekit_api.SIPOutboundTrunkInfo(
name="Vobiz Trunk",
address="YOUR_VOBIZ_SIP_DOMAIN",      # From Vobiz trunk response
auth_username="YOUR_VOBIZ_USERNAME",  # From Vobiz trunk response
auth_password="YOUR_VOBIZ_PASSWORD",  # From Vobiz trunk response
numbers=["YOUR_PHONE_NUMBER"]         # Your Vobiz phone number
)
)
)
# Save trunk.sip_trunk_id - you'll need it for making calls
```
Field Mapping:
Vobiz Field
→
LiveKit Field
sip_domain
→
address
username
→
auth_username
password
→
auth_password
Your phone number
→
numbers (array)
{/* Part 4: Make Outbound Calls */}
## Part 4: Make Outbound Calls
```
participant = await lk.sip.create_sip_participant(
livekit_api.CreateSIPParticipantRequest(
sip_trunk_id="YOUR_TRUNK_ID",         # From previous step
sip_call_to="+1234567890",            # Number to call (E.164 format)
room_name="call-room"                 # LiveKit room name
)
)
```
Call flow:
- LiveKit creates the call via Vobiz
- Person answers → joins LiveKit room as participant
- Your AI agent joins the same room
- Conversation begins
{/* Part 5: Configure Inbound Calling */}
## Part 5: Configure Inbound Calling
**Example Code:** For a complete example of Inbound Caller, check the [LiveKit Vobiz Inbound Repository](https://github.com/vobiz-ai/Livekit-vobiz-inbound).
{/* Step 1: Get LiveKit SIP URI */}
### Step 1: Get LiveKit SIP URI
- Go to [LiveKit Cloud Dashboard](https://cloud.livekit.io)
- Select your project
- Go to **Settings** → **Project**
- Find **SIP URI** field
```
sip:your-project-id.sip.livekit.cloud:5060
```
{/* Step 2: Update Vobiz Trunk */}
### Step 2: Update Vobiz Trunk Inbound Destination
Update your Vobiz trunk to route calls to LiveKit.
**See:** [Vobiz Update Trunk Documentation](/trunks)
⚠️ CRITICAL: Remove the `sip:` prefix when configuring Vobiz!
What LiveKit Shows
What to Enter in Vobiz
sip:project-id.sip.livekit.cloud:5060
project-id.sip.livekit.cloud:5060
```
PATCH https://api.vobiz.ai/api/v1/account/{accountId}/trunks/{trunkId}
```
```
{
"inbound_destination": "project-id.sip.livekit.cloud:5060"
}
```
{/* Step 3: Create LiveKit Inbound Trunk */}
### Step 3: Create LiveKit Inbound Trunk
Via LiveKit Dashboard (Recommended):
- Go to **Telephony** → **Trunks**
- Click **Create new trunk** → **Inbound**
Configure:
- **Phone Numbers:** Your Vobiz number (e.g., `+918071387434`)
- **Allowed Addresses:** `0.0.0.0/0` (restrict in production)
- Click **Create**
- Save the **Trunk ID**
{/* Step 4: Create Dispatch Rule */}
### Step 4: Create Dispatch Rule
Configure LiveKit to auto-spawn your AI agent when calls arrive.
Via LiveKit Dashboard:
- Go to **Telephony** → **Dispatch Rules**
- Click **Create new dispatch rule**
Configure:
- **Rule Type:** Individual
- **Room Prefix:** `call-`
- **Match Trunks:** Select your inbound trunk
- **Expand "Agent dispatch" section**
- Set **Agent Name:** `voice-assistant` (must match your agent)
- Click **Create**
{/* Part 6: SIP Call Transfer */}
## Part 6: SIP Call Transfer
This section outlines how to use the Cold Transfer (SIP REFER) functionality in the LiveKit Voice Agent.
{/* Performing a Transfer */}
### Performing a Transfer
Once you answer the call and are talking to the agent:
#### Default Transfer
Say: **"Transfer me."** or **"Transfer me to a live agent."**
- **Action:** Agent transfers you to the default configured number (`+91XXXXXXXXXX`).
- **Mechanism:** The agent sends a SIP REFER to `sip:+91XXXXXXXXXX@<your-sip-domain>`.
#### Custom Transfer
Say: **"Transfer me to +1 555 000 1234."**
- **Action:** Agent transfers you to the requested number.
- **Mechanism:** The agent constructs `sip:+15550001234@<your-sip-domain>` and initiates the transfer.
{/* 6. Troubleshooting (Transfer specific) */}
### Transfer Troubleshooting
Error
Cause
Solution
Status 500 (Max Auth Retry)
Incorrect SIP credentials on Trunk.
Run `python setup_trunk.py` again to update credentials.
Status 408 (Timeout)
Invalid SIP URI or blocked by provider.
Ensure `VOBIZ_SIP_DOMAIN` is set in `.env`. Verify "Call Transfer (SIP REFER)" is enabled in your SIP provider's dashboard.
Status 400 (Invalid argument)
Destination is not a URI.
The code now automatically adds `sip:` and `@domain`. Update code if using an old version.
Disconnects but no ring
Successful transfer, but destination failed.
The transfer left the agent successfully. Check the destination phone number or SIP provider logs for routing issues.
{/* Troubleshooting */}
## Troubleshooting
{/* Outbound Calls */}
### Outbound Calls
#### Call Doesn't Connect
**Check:**
- `address` in LiveKit trunk matches your exact Vobiz `sip_domain`
- Credentials (`auth_username`, `auth_password`) match exactly
- Common mistake: Using generic `sip.vobiz.ai` instead of your specific domain
#### SIP 401 Unauthorized
- Verify credentials in [Vobiz Console](https://console.vobiz.ai) → Trunks
- Ensure LiveKit trunk has matching credentials
#### Insufficient Balance
- Check balance at [Vobiz Console](https://console.vobiz.ai)
- Add funds if needed
- See [Vobiz Balance docs](/balance)
{/* Inbound Calls */}
### Inbound Calls
#### Call Disconnects Immediately
**Check:**
- Vobiz `inbound_destination` has `sip:` prefix removed
- Vobiz phone number added to LiveKit inbound trunk
- `allowed_addresses` set to `0.0.0.0/0` in LiveKit trunk
#### Agent Doesn't Answer
**Check:**
- Agent is running
- Dispatch rule has "Agent dispatch" configured
- Agent name matches exactly (e.g., `voice-assistant`)
- Dispatch rule linked to correct inbound trunk
{/* Quick Reference */}
## Quick Reference
{/* Required Credentials */}
### Required Credentials
What
Where to Get
Used For
Vobiz sip_domain
Vobiz API trunk response
LiveKit trunk `address`
Vobiz username
Vobiz API trunk response
LiveKit trunk `auth_username`
Vobiz password
Vobiz API trunk response
LiveKit trunk `auth_password`
Vobiz phone number
Vobiz Numbers API
LiveKit trunk `numbers`
LiveKit SIP URI
LiveKit Settings
Vobiz `inbound_destination`
LiveKit trunk ID
After creating trunk
Making calls
{/* Common Errors */}
### Common Errors
Error
Cause
Fix
401 Unauthorized
Credentials mismatch
Verify Vobiz username/password
Call fails silently
Wrong address
Use exact Vobiz sip_domain
Insufficient balance
Low credits
Add funds in Vobiz console
Inbound disconnects
Wrong inbound_destination
Remove sip: prefix
Agent doesn't join
Missing agent dispatch
Configure agent name in dispatch rule
{/* Additional Resources */}
## Additional Resources
{/* Vobiz Documentation */}
### Vobiz Documentation
[API Documentation](/)
[SIP Trunks](/trunks)
[Phone Numbers](/numbers)
[Balance & Billing](/balance)
[Console](https://console.vobiz.ai)
{/* LiveKit Documentation */}
### LiveKit Documentation
[LiveKit Agents](https://docs.livekit.io/agents)
[SIP Integration](https://docs.livekit.io/sip)
[Python SDK](https://docs.livekit.io/client-sdk-python)
{/* Example Repositories */}
### Example Repositories
[Inbound Starter](https://github.com/vobiz-ai/Livekit-vobiz-inbound)
[Outbound & Transfer Starter](https://github.com/vobiz-ai/LiveKit-Vobiz-Outbound)
### Support
**Vobiz:** [support@vobiz.ai](mailto:support@vobiz.ai)
**LiveKit:** [livekit.io/support](https://livekit.io/support)
Integration complete!
Your LiveKit agents can now make and receive calls through Vobiz.
{/* Navigation */}
);
}

---

# Page: /integrations/pipecat

const tableOfContents = [
{ id: 'overview', title: 'Overview', level: 2 },
{ id: 'prerequisites', title: 'Prerequisites', level: 2 },
{ id: 'installation', title: 'Installation', level: 2 },
{ id: 'usage', title: 'Usage', level: 2 },
{ id: 'inbound-calls', title: 'Inbound Calls', level: 2 },
{ id: 'quick-reference', title: 'Quick Reference', level: 2 },
{ id: 'resources', title: 'Resources', level: 2 }
];
return (
{/* Header */}
# Pipecat Integration
Build AI-powered voice agents with Vobiz telephony and Pipecat framework.
**What you'll build:**
An outbound calling system with real-time AI conversations powered by OpenAI (STT → LLM → TTS), automatic call recording, and bidirectional audio streaming.
{/* Overview */}
## Overview
This integration combines **Vobiz** telephony infrastructure with **Pipecat** voice agent framework to create intelligent AI-powered phone calls.
Call flow:
```
curl POST → Vobiz API → Call initiated → Call answered →
Vobiz requests XML → Server returns WebSocket URL →
Audio streams → Pipecat bot (STT → LLM → TTS) →
AI conversation + Recording saved
```
### Features
•
**AI Voice Conversations**
Natural conversations powered by OpenAI GPT + TTS/STT
•
**Outbound Calling**
Trigger calls via REST API from anywhere
•
**Automatic Recording**
All conversations automatically recorded and saved
•
**Real-time Streaming**
Bidirectional audio via WebSockets
{/* Prerequisites */}
## Prerequisites
✓
**Vobiz Account** with Auth ID and Auth Token → [Sign up](https://console.vobiz.ai/auth/signup)
✓
**OpenAI API Key** for LLM, STT, and TTS → [Get API key](https://platform.openai.com)
✓
**Python 3.10+** installed on your system
✓
**ngrok** for local development → [Download ngrok](https://ngrok.com)
{/* Installation */}
## Installation
### Step 1: Clone the Repository
```
git clone https://github.com/vobiz-ai/Vobiz-Pipecat
cd Vobiz-X-Pipecat
```
### Step 2: Install Dependencies
```
pip install -r requirements.txt
```
**Note:** This will install FastAPI, Pipecat, OpenAI SDK, and other required packages.
### Step 3: Configure Environment
Create a `.env` file in the project root:
```
OPENAI_API_KEY=sk-...
VOBIZ_AUTH_ID=MA_XXXXXXXX
VOBIZ_AUTH_TOKEN=your-token-here
PUBLIC_URL=https://your-ngrok-url.ngrok-free.app
```
**Where to find these values:**
- `OPENAI_API_KEY` - OpenAI Platform → API Keys
- `VOBIZ_AUTH_ID` - Vobiz Console → Account Settings
- `VOBIZ_AUTH_TOKEN` - Vobiz Console → Account Settings
- `PUBLIC_URL` - Your ngrok URL (set in Step 2 of Usage)
{/* Usage */}
## Usage
### Step 1: Start the Server
```
python server.py
```
Server will run on `http://0.0.0.0:7860`
### Step 2: Start ngrok
In a new terminal, expose your local server:
```
ngrok http 7860
```
Copy the ngrok URL from the output (e.g., `https://abc123.ngrok-free.app`)
**Important:** Update `PUBLIC_URL` in your `.env` file with this ngrok URL, then restart the server.
### Step 3: Make a Call
Initiate an AI-powered call using the Vobiz API:
```
curl -X POST https://api.vobiz.ai/api/v1/Account/YOUR_AUTH_ID/Call/ \\
-H "X-Auth-ID: YOUR_AUTH_ID" \\
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"from": "+918011223344",
"to": "+919148223344",
"answer_url": "https://your-ngrok-url.ngrok-free.app/answer",
"answer_method": "POST"
}'
```
**What happens next:**
- Phone rings at the "to" number
- When answered, Vobiz requests XML from your server
- Server returns WebSocket URL
- Audio streams to Pipecat bot
- AI assistant speaks and listens
- Conversation is automatically recorded
{/* Inbound Calls */}
## Receiving Inbound Calls
Configure your Vobiz number to handle incoming calls with your Pipecat agent.
### Step 1: Access Applications
Log in to the Vobiz Console and navigate to the **Applications** section in the sidebar.
### Step 2: Create Application
Click "Create New Application" and give it a name (e.g., "Pipecat Agent").
### Step 3: Configure URLs
Set the **Answer URL** to your ngrok URL (e.g., `https://.../answer`) and select POST method. You can use the same URL for Hangup or leave it blank.
### Step 4: Attach Number
Go to "Phone Numbers", select your number, and assign it to the application you just created.
**Success:** Calls to your Vobiz number will now be handled by your local Pipecat server!
{/* Quick Reference */}
## Quick Reference
### Server Endpoints
Endpoint
Method
Description
/answer
POST
Called by Vobiz when call is answered. Returns XML with WebSocket URL.
/ws
WebSocket
WebSocket endpoint for bidirectional audio streaming.
/recording-finished
POST
Called by Vobiz when recording stops. Logs recording details.
/recording-ready
POST
Called by Vobiz when recording file is ready. Auto-downloads the MP3.
### Customizing the Bot
Edit `bot.py` to customize your AI assistant:
```
messages = [
{
"role": "system",
"content": "You are a friendly customer service agent..."
},
]
```
```
tts = OpenAITTSService(
api_key=os.getenv("OPENAI_API_KEY"),
voice="nova",  # Options: alloy, echo, fable, onyx, nova, shimmer
)
```
{/* Resources */}
## Resources
{/* Vobiz Documentation */}
### Vobiz Documentation
[API Documentation](/)
[Make a Call](/call/make-call)
[Vobiz Console](https://console.vobiz.ai)
{/* External Documentation */}
### External Resources
[GitHub Repository](https://github.com/vobiz-ai/Vobiz-Pipecat)
[Pipecat Documentation](https://docs.pipecat.ai)
Integration complete!
You can now make AI-powered phone calls with Vobiz and Pipecat.
Next Steps:
- Customize your AI assistant's personality in bot.py
- Deploy to production (AWS/GCP/Heroku) instead of ngrok
- Add custom business logic and integrations
{/* Navigation */}
);
}

---

# Page: /integrations/elevenlabs-dashboard

const tableOfContents = [
{ id: 'overview', title: 'Overview', level: 2 },
{ id: 'prerequisites', title: 'Prerequisites', level: 2 },
{ id: 'step-1', title: 'Step 1: Import Phone Number', level: 2 },
{ id: 'step-2', title: 'Step 2: Label Your Phone Number', level: 2 },
{ id: 'step-3', title: 'Step 3: Configure Outbound Settings', level: 2 },
{ id: 'step-4', title: 'Step 4: Make Your First Call', level: 2 },
{ id: 'troubleshooting', title: 'Troubleshooting', level: 2 },
{ id: 'next-steps', title: 'Next Steps', level: 2 }
];
return (
{/* Header */}
# ElevenLabs Agent - Dashboard Setup
Connect your ElevenLabs conversational AI agents to Vobiz SIP infrastructure using the visual dashboard interface.
**Prefer using API/CLI?**
Check out the [API-Based Setup Guide](/integrations/elevenlabs-api) for curl commands and programmatic integration.
{/* Overview */}
## Overview
This guide shows how to integrate ElevenLabs with Vobiz using the dashboard to enable **outbound calling** - your AI agents can call any phone number with ultra-realistic voice synthesis.
Call flow:
```
Your App → ElevenLabs Agent → Vobiz SIP → Phone Network → Person Answers → AI Assistant Speaks
```
{/* Prerequisites */}
## Prerequisites
Before starting:
→
**Vobiz Account** with SIP trunk → [Create account](https://console.vobiz.ai/auth/signup)
→
**ElevenLabs Account** → [Sign up](https://elevenlabs.io)
→
**ElevenLabs Agent** created → [Create in dashboard](https://elevenlabs.io/app)
→
**Phone number** from Vobiz (for caller ID)
{/* Step 1 */}
## Step 1: Import Phone Number from SIP Trunk
- Log in to [ElevenLabs Dashboard](https://elevenlabs.io/app)
- Navigate to **Phone Numbers** in the sidebar
- Click **Import Number**
- Select **Import from SIP Trunk**
{/* Step 2 */}
## Step 2: Label Your Phone Number
### Enter Phone Number Details:
**1. Label** - Add a name for easy identification
- Example: "Vobiz Main Line" or "Customer Support Line"
**2. Phone Number** - Enter your Vobiz phone number
- Example: `+911234567890`
- Format: Include country code with `+`
- Alternative format: `01234567890` (without +)
Click **Next** to continue to outbound configuration.
**Need a phone number?** See [Phone Numbers Documentation](/numbers) to purchase one from Vobiz.
{/* Step 3 */}
## Step 3: Configure Outbound Settings
### Outbound Configuration:
1. Transport Type
Select: `TCP`
2. Address (SIP Trunk Address)
Enter your Vobiz SIP domain:
```
abc123def.sip.vobiz.ai
```
This is the hostname where ElevenLabs will send the SIP INVITE
3. SIP Trunk Username
Enter username from Vobiz:
```
your_username
```
4. SIP Trunk Password
Enter password from Vobiz:
```
your_password
```
**Where to get Vobiz credentials:**
- **Via Console:** [Vobiz Console](https://console.vobiz.ai) → Trunks → Your Trunk
- **Via API:** See [SIP Trunks Documentation](/trunks)
Click **Save** or **Import** to complete the setup.
Your phone number is now configured for outbound calling!
{/* Step 4 */}
## Step 4: Make Your First Call
- In ElevenLabs Dashboard, navigate to **Phone Numbers**
- **Select the phone number** you just imported
- Click **Make Outbound Call** button
**Select your agent** from the dropdown
- This is the conversational AI agent you created in ElevenLabs
**Enter the destination phone number**
- Example: `+919988776655`
- Must include country code
- Click **Call** or **Start Test Call**
The call will initiate immediately!
What happens next:
- Phone rings at destination number
- When answered, your ElevenLabs agent speaks
- Agent says the configured "First Message"
- Conversation begins with natural voice interactions
### Verify Your Call:
**View call logs and transcripts:**
- Go to **Agents Platform** → Your Agent
- Click **Call History** or **Conversations**
- View call details, transcripts, and recordings
Dashboard Setup Complete!
You can now make calls from the ElevenLabs Dashboard anytime. Your AI agent can call any phone number through Vobiz SIP infrastructure.
{/* Troubleshooting */}
## Troubleshooting
#### SIP 408 Request Timeout
**Problem:** Vobiz trunk cannot reach ElevenLabs SIP servers.
**Fix:**
- Verify SIP trunk address is correct (e.g., `abc123def.sip.vobiz.ai`)
- Check transport type is set to `TCP`
- Verify Vobiz trunk status is `active` in [Vobiz Console](https://console.vobiz.ai)
#### SIP Authentication Failed
**Problem:** Wrong username or password.
**Fix:**
- Verify username and password in [Vobiz Console](https://console.vobiz.ai) → Trunks
- Ensure credentials match exactly (case-sensitive)
- Re-enter credentials in ElevenLabs dashboard
#### Insufficient Balance
**Problem:** Vobiz account has no credits.
**Fix:**
- Log in to [Vobiz Console](https://console.vobiz.ai) → Billing
- Add funds (minimum ₹100 recommended)
- See [Balance Documentation](/balance)
#### Call Connects But Silent
**Problem:** Agent configuration issue or voice not set.
**Fix:**
- Verify agent has "First Message" configured in ElevenLabs dashboard
- Check agent has valid voice selected
- Test voice in ElevenLabs dashboard first
- View call logs in [ElevenLabs Dashboard](https://elevenlabs.io/app) for errors
#### Call Doesn't Connect
**Problem:** Wrong phone number format or trunk configuration.
**Fix:**
- Use E.164 format: `+919988776655` (with +)
- Or local format: `09988776655` (without +)
- Verify Vobiz trunk is active
- Check Vobiz [CDR logs](/cdr) for call attempts
**Need more detailed troubleshooting?**
Check the [complete troubleshooting guide](/integrations/elevenlabs-api#troubleshooting) in the API documentation for more error scenarios and solutions.
{/* Next Steps */}
## Next Steps
→
**Customize your agent**
Configure voice, personality, prompts, and first message in [ElevenLabs Dashboard](https://elevenlabs.io/app)
→
**View call analytics**
Monitor call logs, transcripts, and conversation history in ElevenLabs Dashboard → Call History
→
**Automate with API**
Learn to trigger calls programmatically in the [API Setup Guide](/integrations/elevenlabs-api)
→
**Monitor usage**
Track Vobiz [balance](/balance) and [call records](/cdr)
{/* Navigation */}
);
}

---

# Page: /integrations/elevenlabs-api

const tableOfContents = [
{ id: 'overview', title: 'Overview', level: 2 },
{ id: 'prerequisites', title: 'Prerequisites', level: 2 },
{ id: 'vobiz-setup', title: 'Part 1: Vobiz Setup', level: 2 },
{ id: 'elevenlabs-setup', title: 'Part 2: ElevenLabs Setup', level: 2 },
{ id: 'integration', title: 'Part 3: Integration (2 Steps)', level: 2 },
{ id: 'verification', title: 'Verification', level: 2 },
{ id: 'troubleshooting', title: 'Troubleshooting', level: 2 },
{ id: 'quick-reference', title: 'Quick Reference', level: 2 },
{ id: 'complete-example', title: 'Complete Example', level: 2 },
{ id: 'resources', title: 'Additional Resources', level: 2 }
];
return (
{/* Header */}
# ElevenLabs Agent - API Setup
Connect your ElevenLabs AI agents to Vobiz SIP infrastructure using API/CLI commands for programmatic automation.
**Prefer using the Dashboard?**
Check out the [Dashboard Setup Guide](/integrations/elevenlabs-dashboard) for a visual step-by-step walkthrough.
{/* Overview */}
## Overview
This guide shows how to integrate ElevenLabs with Vobiz programmatically to enable **outbound calling** - automate voice calls with ultra-realistic AI voices.
Call flow:
```
Your App → ElevenLabs API → Vobiz SIP → Phone Network → Person Answers → AI Agent Speaks
```
**Perfect for:**
- Application integration
- Bulk calling campaigns
- Automation workflows
- Custom call triggers
{/* Prerequisites */}
## Prerequisites
→
**Vobiz Account** with SIP trunk → [Create account](https://console.vobiz.ai/auth/signup)
→
**ElevenLabs Account** with API key → [Sign up](https://elevenlabs.io)
→
**ElevenLabs API Key** → [Get API key](https://elevenlabs.io/app/settings/api-keys)
→
**Phone number** from Vobiz (for caller ID)
{/* Part 1: Vobiz Setup */}
## Part 1: Vobiz Setup
### Create SIP Trunk
Create a SIP trunk in Vobiz to handle voice traffic.
**See:** [Vobiz SIP Trunks Documentation](/trunks)
**Save these values from the response:**
- `sip_domain` (e.g., `abc123def.sip.vobiz.ai`)
- `username`
- `password`
You'll need them for ElevenLabs configuration.
### Get Phone Number
Purchase a phone number for outbound caller ID.
**See:** [Vobiz Phone Numbers Documentation](/numbers)
{/* Part 2: ElevenLabs Setup */}
## Part 2: ElevenLabs Setup
### Step 1: Get API Key
**Via Dashboard:**
- Go to [ElevenLabs Settings → API Keys](https://elevenlabs.io/app/settings/api-keys)
- Click **Create API Key**
- Name your key (e.g., "Vobiz Integration")
Set permissions:
- **ElevenLabs Agents:** **Write** (Required)
- **Voices:** **Read** (Required)
- **User:** Read (Optional)
- Click **Create** and copy the key
```
sk_your_elevenlabs_api_key_here
```
**Save this key securely** - you'll use it in all API requests.
### Step 2: List Available Voices
```
curl "https://api.elevenlabs.io/v1/voices" \\
-H "xi-api-key: sk_your_elevenlabs_api_key_here"
```
**What to extract:**
- `voice_id` - Use this when creating your agent
- `name` - Voice name for identification
- `category` - Voice type (premade, cloned, etc.)
```
{
"voices": [
{
"voice_id": "voice_id_here",
"name": "Rachel",
"category": "premade",
"labels": {
"accent": "american",
"age": "young"
}
},
{
"voice_id": "another_voice_id",
"name": "Domi",
"category": "premade"
}
]
}
```
**Copy a `voice_id`** - you'll need it in Step 3.
### Step 3: Create Agent
```
curl -X POST "https://api.elevenlabs.io/v1/convai/agents" \\
-H "Content-Type: application/json" \\
-H "xi-api-key: sk_your_elevenlabs_api_key_here" \\
-d '{
"name": "Customer Support Bot",
"conversation_config": {
"agent": {
"prompt": {
"prompt": "You are a helpful customer support assistant. Be friendly, professional, and concise."
},
"first_message": "Hello! Thank you for calling. How can I help you today?",
"language": "en"
},
"tts": {
"voice_id": "voice_id_here"
}
}
}'
```
**Replace:**
- `voice_id_here` → Your chosen voice ID from Step 2
```
{
"agent_id": "agent_your_agent_id_here",
"name": "Customer Support Bot",
"conversation_config": {
"agent": {
"first_message": "Hello! Thank you for calling. How can I help you today?",
"language": "en"
}
}
}
```
**Save the `agent_id`** - you'll need it to make calls.
{/* Part 3: Integration */}
## Part 3: Connect Vobiz to ElevenLabs (2 Steps)
### Step 1: Import Phone Number via API
This registers your Vobiz phone number with ElevenLabs for outbound calling.
```
curl -X POST "https://api.elevenlabs.io/v1/convai/phone-numbers" \\
-H "Content-Type: application/json" \\
-H "xi-api-key: sk_your_elevenlabs_api_key_here" \\
-d '{
"phone_number": "+911234567890",
"label": "Vobiz Main Line",
"provider": "sip_trunk",
"outbound_trunk": {
"address": "abc123def.sip.vobiz.ai",
"transport": "tcp",
"username": "your_username",
"password": "your_password"
}
}'
```
**Replace:**
- `+911234567890` → Your Vobiz phone number
- `abc123def.sip.vobiz.ai` → Your Vobiz SIP domain
- `your_username` → Your Vobiz username
- `your_password` → Your Vobiz password
```
{
"phone_number_id": "phnum_your_phone_number_id_here",
"phone_number": "+911234567890",
"label": "Vobiz Main Line",
"supports_outbound": true,
"supports_inbound": true,
"provider": "sip_trunk"
}
```
**Save the `phone_number_id`** - you'll need it in Step 2.
**Get Vobiz Credentials:**
- **Via Console:** [Vobiz Console](https://console.vobiz.ai) → Trunks
- **Via API:** [Vobiz API Reference](/trunks)
### Step 2: Make Outbound Call
Now you can make calls using your AI agent!
```
curl -X POST "https://api.elevenlabs.io/v1/convai/sip-trunk/outbound-call" \\
-H "Content-Type: application/json" \\
-H "xi-api-key: sk_your_elevenlabs_api_key_here" \\
-d '{
"agent_id": "agent_your_agent_id_here",
"agent_phone_number_id": "phnum_your_phone_number_id_here",
"to_number": "+919988776655"
}'
```
**Replace:**
- `agent_your_agent_id_here` → Your agent ID from Part 2, Step 3
- `phnum_your_phone_number_id_here` → Your phone number ID from Step 1
- `+919988776655` → Destination number to call
```
{
"success": true,
"message": "Outbound call initiated",
"conversation_id": "conv_your_conversation_id_here",
"sip_call_id": "SCL_your_sip_call_id"
}
```
**Call initiated via API!**
What happens next:
- Phone rings at destination
- When answered, agent speaks
- Conversation begins with natural voice
{/* Verification */}
## Verification
### List Your Agents
```
curl "https://api.elevenlabs.io/v1/convai/agents" \\
-H "xi-api-key: sk_your_elevenlabs_api_key_here"
```
```
[
{
"agent_id": "agent_your_agent_id_here",
"name": "Customer Support Bot",
"conversation_config": {
"agent": {
"first_message": "Hello! How can I help you today?",
"language": "en"
}
}
}
]
```
### Check Call Logs
View your call history in [ElevenLabs Dashboard](https://elevenlabs.io/app) → Call History
**Test Call Flow:**
- Run Step 2 to initiate a call
- Wait for destination phone to ring
- Answer the call
- AI agent will greet and speak
- Check call transcript in ElevenLabs Dashboard
{/* Troubleshooting */}
## Troubleshooting
#### "Unauthorized" / 401 Error
**Problem:** ElevenLabs API Key is invalid or expired.
**Fix:**
- Verify you copied the entire key (starts with `sk_`)
- Check API key has **ElevenLabs Agents: Write** permission
- Generate new key at [ElevenLabs Settings](https://elevenlabs.io/app/settings/api-keys)
#### "Not Found" / 404 Error
**Problem:** Agent ID or Phone Number ID doesn't exist.
**Fix:**
- List your agents to verify agent ID is correct
- Check phone number is configured in [ElevenLabs Dashboard](https://elevenlabs.io/app)
- Ensure you're using the correct ID format
#### SIP 408 Request Timeout
**Problem:** Vobiz trunk cannot reach ElevenLabs SIP servers.
**Fix:**
- Verify Vobiz trunk configuration in [Vobiz Console](https://console.vobiz.ai)
- Ensure transport is set to `tcp`
- Check trunk status is `active`
- See: [Vobiz SIP Trunks Guide](/trunks)
#### "Insufficient Balance"
**Problem:** Vobiz account has no credits.
**Fix:**
- Log in to [Vobiz Console](https://console.vobiz.ai) → Billing
- Add funds (minimum ₹100 recommended)
#### Call Connects But Silent
**Problem:** Agent configuration issue or voice not set.
**Fix:**
- Verify agent has `first_message` configured
- Check agent has valid `voice_id` in conversation_config
- Test voice in ElevenLabs dashboard first
- View call logs in [ElevenLabs Dashboard](https://elevenlabs.io/app)
#### Call Doesn't Connect
**Problem:** Wrong phone number format or trunk configuration.
**Fix:**
- Use E.164 format: `+919988776655` (with + and country code)
- Verify Vobiz trunk is active
- Check Vobiz CDR logs for call attempts at [Vobiz Console](https://console.vobiz.ai)
- Ensure phone number is not blocked
{/* Quick Reference */}
## Quick Reference
{/* Required Credentials */}
### Required Credentials
What
Where to Get
Example
ElevenLabs API Key
ElevenLabs Settings → API Keys
sk_your_elevenlabs_api_key_here
Voice ID
Part 2, Step 2: List Voices
voice_id_here
Agent ID
Part 2, Step 3: Create Agent
agent_your_agent_id_here
Phone Number ID
Part 3, Step 1: Import Phone
phnum_your_phone_number_id_here
Vobiz SIP Domain
Vobiz Console → Trunks
abc123def.sip.vobiz.ai
Vobiz Username
Vobiz Console → Trunks
your_username
Vobiz Password
Vobiz Console → Trunks
your_password
{/* API Endpoints */}
### API Endpoints
Action
Method
Endpoint
List Voices
GET
/v1/voices
Create Agent
POST
/v1/convai/agents
List Agents
GET
/v1/convai/agents
Import Phone Number
POST
/v1/convai/phone-numbers
Make Outbound Call
POST
/v1/convai/sip-trunk/outbound-call
**Base URL:** `https://api.elevenlabs.io`
**All requests require:** `xi-api-key: YOUR_ELEVENLABS_API_KEY`
{/* Common Errors */}
### Common Errors
Error
Cause
Fix
401 Unauthorized
Wrong API Key
Check key in ElevenLabs Settings
404 Not Found
Wrong Agent/Phone ID
List agents to verify IDs
408 SIP timeout
Trunk config wrong
Check Vobiz Console → Trunks
Insufficient balance
Low Vobiz credits
Add funds in Vobiz Console
{/* Complete Example */}
## Complete Example
Here's a complete working example with real values:
```
curl "https://api.elevenlabs.io/v1/voices" \\
-H "xi-api-key: sk_your_elevenlabs_api_key_here"
# Save a voice_id from the response
```
```
curl -X POST "https://api.elevenlabs.io/v1/convai/agents" \\
-H "Content-Type: application/json" \\
-H "xi-api-key: sk_your_elevenlabs_api_key_here" \\
-d '{
"name": "Customer Support Bot",
"conversation_config": {
"agent": {
"prompt": {
"prompt": "You are a helpful customer support assistant."
},
"first_message": "Hello! How can I help you today?",
"language": "en"
},
"tts": {
"voice_id": "voice_id_here"
}
}
}'
# Response: Save agent_id
```
```
curl -X POST "https://api.elevenlabs.io/v1/convai/phone-numbers" \\
-H "Content-Type: application/json" \\
-H "xi-api-key: sk_your_elevenlabs_api_key_here" \\
-d '{
"phone_number": "+911234567890",
"label": "Vobiz Main Line",
"provider": "sip_trunk",
"outbound_trunk": {
"address": "abc123def.sip.vobiz.ai",
"transport": "tcp",
"username": "your_username",
"password": "your_password"
}
}'
# Response: Save phone_number_id
```
```
curl -X POST "https://api.elevenlabs.io/v1/convai/sip-trunk/outbound-call" \\
-H "Content-Type: application/json" \\
-H "xi-api-key: sk_your_elevenlabs_api_key_here" \\
-d '{
"agent_id": "agent_your_agent_id_here",
"agent_phone_number_id": "phnum_your_phone_number_id_here",
"to_number": "+919988776655"
}'
# Response: Call initiated!
```
{/* Additional Resources */}
## Additional Resources
{/* Vobiz Documentation */}
### Vobiz Documentation
[API Documentation](/)
[Console](https://console.vobiz.ai)
[SIP Trunks](/trunks)
[Phone Numbers](/numbers)
{/* ElevenLabs Documentation */}
### ElevenLabs Documentation
[API Reference](https://elevenlabs.io/docs/api-reference/introduction)
[Dashboard](https://elevenlabs.io/app)
[Agents Platform](https://elevenlabs.io/docs/agents-platform)
[Support](mailto:support@elevenlabs.io)
Integration complete!
Your ElevenLabs agents can now make outbound calls through Vobiz with ultra-realistic voices.
Next Steps:
- Customize your agent in [ElevenLabs Dashboard](https://elevenlabs.io/app)
- View call logs and conversation transcripts
- Build your voice AI application!
{/* Navigation */}
);
}

---

# Page: /integrations/vapi-dashboard

const tableOfContents = [
{ id: 'overview', title: 'Overview', level: 2 },
{ id: 'prerequisites', title: 'Prerequisites', level: 2 },
{ id: 'step-1', title: 'Step 1: Create SIP Trunk Credentials', level: 2 },
{ id: 'step-2-3', title: 'Step 2 & 3: Get Vobiz Credentials', level: 2 },
{ id: 'step-4', title: 'Step 4: Import Phone Number', level: 2 },
{ id: 'step-5', title: 'Step 5: Make Outbound Call', level: 2 },
{ id: 'step-6', title: 'Step 6: Configure Call Transfer Tool', level: 2 },
{ id: 'troubleshooting', title: 'Troubleshooting', level: 2 },
{ id: 'next-steps', title: 'Next Steps', level: 2 }
];
return (
{/* Header */}
# Vapi Integration - Dashboard Setup
Connect your Vapi AI assistants to Vobiz SIP infrastructure using the visual dashboard interface.
**Prefer using API/CLI?**
Check out the [API-Based Setup Guide](/integrations/vapi-api) for curl commands and programmatic integration.
{/* Overview */}
## Overview
This guide shows how to integrate Vapi with Vobiz using the dashboard to enable **outbound calling** - your AI assistants can call any phone number.
Call flow:
```
Your App → Vapi API → Vobiz SIP → Phone Network → Person Answers → AI Assistant Speaks
```
{/* Prerequisites */}
## Prerequisites
Before starting:
✓
**Vobiz Account** with SIP trunk → [Create account](https://console.vobiz.ai/auth/signup)
✓
**Vapi Account** → [Sign up](https://dashboard.vapi.ai/signup)
✓
**Vapi Assistant** created → [Create in dashboard](https://dashboard.vapi.ai)
✓
**Phone number** from Vobiz (for caller ID)
{/* Step 1 */}
## Step 1: Create SIP Trunk Credentials in Vapi
- Log in to [Vapi Dashboard](https://dashboard.vapi.ai)
- Click on **Integrations** in the sidebar
- Navigate to **SIP Trunk Credentials**
- Click **Add New Credential**
- **Name your trunk** (e.g., "Vobiz Trunk")
- **Add Gateway URL**: Enter your Vobiz SIP domain from Vobiz Console (e.g., `bfab10fb.sip.vobiz.ai`)
- **Add Credentials**: Enter username and password from your Vobiz trunk
- **Enable outbound calling**
- Click **Save**
**Need your Vobiz credentials?** Continue to Step 2 & 3 below to get them from Vobiz Console.
{/* Step 2 & 3 */}
## Step 2 & 3: Get Vobiz SIP Credentials
From Vobiz Console:
- Log in to [Vobiz Console](https://console.vobiz.ai)
- Go to **Trunks**
- Select your trunk
- Copy the **SIP Domain**, **Username**, and **Password**
Use these credentials in Vapi:
- **SIP Domain/Gateway URL:** `bfab10fb.sip.vobiz.ai`
- **Username:** `Vapi_user`
- **Password:** `Password@123`
These are the credentials you enter in Step 1 above.
**Note:** Don't have a Vobiz trunk yet? See [SIP Trunks Documentation](/trunks) to create one.
{/* Step 4 */}
## Step 4: Import Your Phone Number
- In Vapi Dashboard, go to **Phone Numbers**
- Click **Add Number**
- Select **BYO SIP Trunk Number**
- **Enter your Vobiz number** (e.g., `08071387149` - the number you purchased from Vobiz)
- **Select SIP Trunk Credentials**: Choose the credential you created in Step 1
- **Give it a label/name** (e.g., "Vobiz Main Line")
- Click **Import SIP Trunk Number**
Your phone number is now registered and ready for outbound calling!
**Need a phone number?** See [Phone Numbers Documentation](/numbers) to purchase one from Vobiz.
{/* Step 5 */}
## Step 5: Make an Outbound Call
- In Vapi Dashboard, click **Make a Call** or go to **Phone Calls** → **New Call**
- Go to **Outbound Settings**
- **Enter the phone number** you want to call (e.g., `+919148223344`)
- **Select your assistant** from the dropdown
- **Select the phone number** to call from (your imported Vobiz number)
- Click **Make Outbound Call**
- **The call will initiate!**
Integration Complete!
Your Vapi assistant can now make outbound calls through Vobiz SIP infrastructure.
{/* Step 6 */}
## Step 6: Configure Call Transfer Tool
To enable the AI agent to transfer calls to a human agent or another department, you need to configure the "Transfer Call" tool.
1. Select "Transfer Call" from Tools menu
2. Configure Destination and Transfer Mode
- In the Vapi Dashboard, navigate to the **Tools** section.
- Click **Create Tool** and select **Transfer Call** from the dropdown menu.
- **Phone Number**: Enter the destination number in E.164 format (e.g., `+919876543210`).
- **Transfer Mode**: Select **Blind Transfer**.
- Click **Create Destination** or **Save** to confirm.
**Note:** Blind Transfer forwards the call immediately without the AI announcing the caller.
{/* Troubleshooting */}
## Troubleshooting
#### Call Doesn't Connect
**Problem:** SIP authentication fails or call doesn't go through.
**Fix:**
- Verify SIP domain, username, password are correct in [Vobiz Console](https://console.vobiz.ai)
- Ensure you're using the exact `sip_domain` (e.g., `bfab10fb.sip.vobiz.ai`)
- Don't use generic `sip.vobiz.ai`
#### Insufficient Balance
**Problem:** Call fails due to low Vobiz credits.
**Fix:**
- Log in to [Vobiz Console](https://console.vobiz.ai) → Billing
- Add funds (minimum ₹100 recommended)
- See [Balance Documentation](/balance)
#### Assistant Doesn't Speak
**Problem:** Call connects but assistant is silent.
**Fix:**
- Verify assistant has "First Message" configured in Vapi dashboard
- Check assistant has voice provider set up correctly
- View call logs in [Vapi Dashboard](https://dashboard.vapi.ai) → Calls for errors
#### Phone Number Format Error
**Problem:** Number not recognized or invalid format.
**Fix:**
- Use E.164 format: `+919148223344` (with +)
- Or local format: `09148223344` (without +)
- Verify the number is active in [Vobiz Console](https://console.vobiz.ai)
**Need more detailed troubleshooting?**
Check the [complete troubleshooting guide](/integrations/vapi-api#troubleshooting) in the API documentation for more error scenarios and solutions.
{/* Next Steps */}
## Next Steps
→
**Customize your assistant**
Configure voice, personality, and responses in [Vapi Dashboard](https://dashboard.vapi.ai)
→
**View call analytics**
Monitor call logs, transcripts, and metrics in Vapi Dashboard → Calls
→
**Automate with API**
Learn to trigger calls programmatically in the [API Setup Guide](/integrations/vapi-api)
→
**Monitor usage**
Track Vobiz [balance](/balance) and [call records](/cdr)
{/* Navigation */}
);
}

---

# Page: /integrations/vapi-api

const tableOfContents = [
{ id: 'overview', title: 'Overview', level: 2 },
{ id: 'prerequisites', title: 'Prerequisites', level: 2 },
{ id: 'vobiz-setup', title: 'Part 1: Vobiz Setup', level: 2 },
{ id: 'vapi-setup', title: 'Part 2: Vapi Setup', level: 2 },
{ id: 'integration', title: 'Part 3: Integration (3 Steps)', level: 2 },
{ id: 'verification', title: 'Verification', level: 2 },
{ id: 'troubleshooting', title: 'Troubleshooting', level: 2 },
{ id: 'quick-reference', title: 'Quick Reference', level: 2 },
{ id: 'complete-example', title: 'Complete Example', level: 2 },
{ id: 'resources', title: 'Additional Resources', level: 2 }
];
return (
{/* Header */}
# Vapi Integration - API Setup
Connect your Vapi AI assistants to Vobiz SIP infrastructure using API/CLI commands.
**Prefer using the Dashboard?**
Check out the [Dashboard Setup Guide](/integrations/vapi-dashboard) for a visual step-by-step walkthrough.
{/* Overview */}
## Overview
This guide shows how to integrate Vapi with Vobiz programmatically to enable **outbound calling** - your AI assistants can call any phone number.
Call flow:
```
Your App → Vapi API → Vobiz SIP → Phone Network → Person Answers → AI Assistant Speaks
```
{/* Prerequisites */}
## Prerequisites
✓
**Vobiz Account** with SIP trunk → [Create account](https://console.vobiz.ai/auth/signup)
✓
**Vapi Account** with private key → [Sign up](https://dashboard.vapi.ai/signup)
✓
**Vapi Assistant** created → [Create in dashboard](https://dashboard.vapi.ai)
✓
**Phone number** from Vobiz (optional, for caller ID)
{/* Part 1: Vobiz Setup */}
## Part 1: Vobiz Setup
### Create SIP Trunk
Create a SIP trunk in Vobiz to handle voice traffic.
**See:** [Vobiz SIP Trunks Documentation](/trunks)
**Save these values from the response:**
- `sip_domain` (e.g., `5f3a607b.sip.vobiz.ai`)
- `username`
- `password`
You'll need them for Vapi configuration.
### Get Phone Number
Purchase a phone number for outbound caller ID or inbound calls.
**See:** [Vobiz Phone Numbers Documentation](/numbers)
{/* Part 2: Vapi Setup */}
## Part 2: Vapi Setup
### Get Vapi Private Key
- Log in to [Vapi Dashboard](https://dashboard.vapi.ai)
- Click your profile icon (top right)
- Go to **Settings** → **API Keys**
- Click **Create new key**
- Copy the key
```
c07947df-6ba2-4e58-92f5-35e92849f6c2
```
**Save this key** - you'll use it in all API requests.
### Get Assistant ID
- In [Vapi Dashboard](https://dashboard.vapi.ai), go to **Assistants**
- Select your assistant (or create one)
- Copy the **Assistant ID**
```
9fb6d4c5-9403-49ea-afeb-9b493d63b474
```
**Or list via API:**
```
curl "https://api.vapi.ai/assistant" \\
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY"
```
{/* Part 3: Integration */}
## Part 3: Connect Vobiz to Vapi (3 Steps)
### Step 1: Create SIP Credential in Vapi
This registers your Vobiz SIP trunk with Vapi for outbound calling.
```
curl -X POST "https://api.vapi.ai/credential" \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \\
-d '{
"provider": "byo-sip-trunk",
"name": "Vobiz Trunk",
"gateways": [{
"ip": "bfab10fb.sip.vobiz.ai",
"inboundEnabled": false
}],
"outboundLeadingPlusEnabled": true,
"outboundAuthenticationPlan": {
"authUsername": "Vapi_user",
"authPassword": "Password@123"
}
}'
```
**Replace:**
- `bfab10fb.sip.vobiz.ai` → Your Vobiz SIP domain
- `Vapi_user` → Your Vobiz username
- `Password@123` → Your Vobiz password
```
{
"id": "65a79bd2-c1b9-4c83-8e55-97c22c092b48",
"provider": "byo-sip-trunk",
"gateways": [{
"ip": "bfab10fb.sip.vobiz.ai",
"inboundEnabled": false
}],
...
}
```
**Save the `id` field** - this is your **Credential ID**.
### Step 2: Register Phone Number
This associates your phone number with the SIP credential for caller ID.
```
curl -X POST "https://api.vapi.ai/phone-number" \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \\
-d '{
"provider": "byo-phone-number",
"name": "Vobiz Line",
"number": "08071387149",
"numberE164CheckEnabled": false,
"credentialId": "65a79bd2-c1b9-4c83-8e55-97c22c092b48"
}'
```
**Replace:**
- `08071387149` → Your Vobiz phone number
- `65a79bd2-c1b9-4c83-8e55-97c22c092b48` → Your Credential ID from Step 1
```
{
"id": "91122039-9644-47fd-a545-d865075a6941",
"number": "08071387149",
"status": "active",
"credentialId": "65a79bd2-c1b9-4c83-8e55-97c22c092b48",
...
}
```
**Save the `id` field** - this is your **Phone Number ID**.
### Step 3: Make Outbound Call
Now you can make calls using your AI assistant!
```
curl -X POST "https://api.vapi.ai/call/phone" \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \\
-d '{
"assistantId": "9fb6d4c5-9403-49ea-afeb-9b493d63b474",
"customer": {
"number": "+919148223344",
"numberE164CheckEnabled": false
},
"phoneNumberId": "91122039-9644-47fd-a545-d865075a6941"
}'
```
**Replace:**
- `9fb6d4c5-9403-49ea-afeb-9b493d63b474` → Your Assistant ID
- `+919148223344` → Destination number to call
- `91122039-9644-47fd-a545-d865075a6941` → Your Phone Number ID from Step 2
```
{
"id": "019a0bce-0cf3-7337-a253-f65f4e9c68f4",
"status": "queued",
"type": "outboundPhoneCall",
"assistantId": "9fb6d4c5-9403-49ea-afeb-9b493d63b474",
"customer": {
"number": "+919148223344"
},
"phoneNumberId": "91122039-9644-47fd-a545-d865075a6941",
...
}
```
**Call initiated!** The phone will ring, and when answered, your AI assistant will speak.
{/* Verification */}
## Verification
### Check Call Status
View your call logs in [Vapi Dashboard](https://dashboard.vapi.ai) → **Calls**
Or via API:
```
curl "https://api.vapi.ai/call/019a0bce-0cf3-7337-a253-f65f4e9c68f4" \\
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY"
```
### Test Call Flow
- Run Step 3 to initiate a call
- Wait for destination phone to ring
- Answer the call
- AI assistant will greet and speak
- Check call transcript in Vapi Dashboard
{/* Troubleshooting */}
## Troubleshooting
#### "Unauthorized" / "Invalid API Key"
**Problem:** Vapi Private Key is incorrect.
**Fix:**
- Verify you copied the entire key
- Generate new key at [Vapi Dashboard](https://dashboard.vapi.ai) → Settings → API Keys
#### "Couldn't Get Assistant"
**Problem:** Wrong Assistant ID or doesn't exist.
**Fix:**
- Run: `curl "https://api.vapi.ai/assistant" -H "Authorization: Bearer YOUR_KEY"`
- Use the correct `id` from the response
- Don't confuse Credential ID with Assistant ID
#### "SIP Authentication Failed"
**Problem:** Vobiz credentials are incorrect.
**Fix:**
- Verify SIP domain, username, password in [Vobiz Console](https://console.vobiz.ai)
- Ensure you're using the exact `sip_domain` (e.g., `bfab10fb.sip.vobiz.ai`)
- Don't use generic `sip.vobiz.ai`
#### "Insufficient Balance"
**Problem:** Vobiz account has no credits.
**Fix:**
- Log in to [Vobiz Console](https://console.vobiz.ai) → Billing
- Add funds (minimum ₹100 recommended)
#### Call Connects But Silent
**Problem:** Assistant configuration issue.
**Fix:**
- Verify assistant has "First Message" configured in Vapi dashboard
- Check assistant has voice provider set up
- View call logs in [Vapi Dashboard](https://dashboard.vapi.ai) → Calls
#### Call Doesn't Connect
**Problem:** Wrong phone number format or trunk configuration.
**Fix:**
- Use E.164 format: `+919148223344` (with +)
- Or local format: `09148223344` (without +)
- Verify Vobiz trunk is active in [Vobiz Console](https://console.vobiz.ai)
- Check Vobiz [CDR logs](/cdr) for call attempts
{/* Quick Reference */}
## Quick Reference
{/* Required Credentials */}
### Required Credentials
What
Where to Get
Used In
Vapi Private Key
Vapi Dashboard → Settings → API Keys
All API requests
Vobiz SIP Domain
Vobiz Console → Trunks → sip_domain
Step 1: gateways[0].ip
Vobiz Username
Vobiz Console → Trunks → Username
Step 1: authUsername
Vobiz Password
Vobiz Console → Trunks → Password
Step 1: authPassword
Phone Number
Vobiz Console → Numbers
Step 2: number
Credential ID
Step 1 response → id
Step 2: credentialId
Phone Number ID
Step 2 response → id
Step 3: phoneNumberId
Assistant ID
Vapi Dashboard → Assistants → Assistant ID
Step 3: assistantId
{/* Field Mapping */}
### Field Mapping: Vobiz → Vapi
Vobiz Field
→
Vapi Field
Step
sip_domain
→
gateways[0].ip
1
username
→
outboundAuthenticationPlan.authUsername
1
password
→
outboundAuthenticationPlan.authPassword
1
Phone number
→
number
2
{/* API Endpoints */}
### API Endpoints
Action
Method
Endpoint
Create SIP Credential
POST
https://api.vapi.ai/credential
Register Phone Number
POST
https://api.vapi.ai/phone-number
Make Outbound Call
POST
https://api.vapi.ai/call/phone
List Assistants
GET
https://api.vapi.ai/assistant
Get Call Details
GET
https://api.vapi.ai/call/{`{callId}`}
**All requests require:**
`Authorization: Bearer YOUR_VAPI_PRIVATE_KEY`
{/* Common Errors */}
### Common Errors
Error
Cause
Fix
401 Unauthorized
Wrong Vapi Private Key
Verify key in dashboard
Assistant Does Not Exist
Wrong Assistant ID
List assistants via API
SIP auth failed
Wrong Vobiz credentials
Check Vobiz Console → Trunks
Insufficient balance
Low Vobiz credits
Add funds in Vobiz Console
Phone format error
Missing + or country code
Use +919148223344 or 09148223344
{/* Complete Example */}
## Complete Example
Here's a complete working example with real values from our setup:
```
curl -X POST "https://api.vapi.ai/credential" \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer c07947df-6ba2-4e58-92f5-35e92849f6c2" \\
-d '{
"provider": "byo-sip-trunk",
"name": "Vobiz Trunk 2",
"gateways": [{
"ip": "bfab10fb.sip.vobiz.ai",
"inboundEnabled": false
}],
"outboundLeadingPlusEnabled": true,
"outboundAuthenticationPlan": {
"authUsername": "Vapi_user",
"authPassword": "Password@123"
}
}'
# Response: Save credential ID
# {"id": "65a79bd2-c1b9-4c83-8e55-97c22c092b48", ...}
```
```
curl -X POST "https://api.vapi.ai/phone-number" \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer c07947df-6ba2-4e58-92f5-35e92849f6c2" \\
-d '{
"provider": "byo-phone-number",
"name": "Vobiz Line 2",
"number": "08071387149",
"numberE164CheckEnabled": false,
"credentialId": "65a79bd2-c1b9-4c83-8e55-97c22c092b48"
}'
# Response: Save phone number ID
# {"id": "91122039-9644-47fd-a545-d865075a6941", ...}
```
```
curl -X POST "https://api.vapi.ai/call/phone" \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer c07947df-6ba2-4e58-92f5-35e92849f6c2" \\
-d '{
"assistantId": "9fb6d4c5-9403-49ea-afeb-9b493d63b474",
"customer": {
"number": "+919148223344",
"numberE164CheckEnabled": false
},
"phoneNumberId": "91122039-9644-47fd-a545-d865075a6941"
}'
# Response: Call initiated!
# {"id": "019a0bce-0cf3-7337-a253-f65f4e9c68f4", "status": "queued", ...}
```
{/* Additional Resources */}
## Additional Resources
{/* Vobiz Documentation */}
### Vobiz Documentation
[API Documentation](/)
[Console](https://console.vobiz.ai)
[SIP Trunks](/trunks)
[Phone Numbers](/numbers)
{/* Vapi Documentation */}
### Vapi Documentation
[API Reference](https://docs.vapi.ai/api-reference)
[Dashboard](https://dashboard.vapi.ai)
[Assistants Guide](https://docs.vapi.ai/assistants)
[Phone Calling](https://docs.vapi.ai/phone)
### Support
**Vobiz:** [support@vobiz.ai](mailto:support@vobiz.ai)
**Vapi:** [Vapi Discord](https://discord.gg/vapi) or support@vapi.ai
Integration complete!
Your Vapi assistants can now make outbound calls through Vobiz.
Next Steps:
- Customize your assistant in [Vapi Dashboard](https://dashboard.vapi.ai)
- View call logs and analytics in Vapi Dashboard
- Build your voice AI application!
{/* Navigation */}
);
}

---

# Page: /integrations/retellai-dashboard

const tableOfContents = [
{ id: 'overview', title: 'Overview', level: 2 },
{ id: 'prerequisites', title: 'Prerequisites', level: 2 },
{ id: 'step-1', title: 'Step 1: Open Phone Numbers', level: 2 },
{ id: 'step-2', title: 'Step 2: Select SIP Trunking', level: 2 },
{ id: 'step-3', title: 'Step 3: Configure SIP Trunk', level: 2 },
{ id: 'step-4', title: 'Step 4: Make a Batch Call', level: 2 },
{ id: 'troubleshooting', title: 'Troubleshooting', level: 2 },
{ id: 'next-steps', title: 'Next Steps', level: 2 }
];
return (
{/* Header */}
# Retell AI - Dashboard Setup
Connect your Retell AI conversational agents to Vobiz SIP infrastructure using the visual dashboard interface.
**Prefer using API/CLI?**
Check out the [API-Based Setup Guide](/integrations/retellai-api) for curl commands and programmatic integration.
{/* Overview */}
## Overview
This guide shows how to integrate Retell AI with Vobiz using the dashboard to enable **outbound calling** - your AI agents can call any phone number with natural conversations.
Call flow:
```
Your App → Retell AI Agent → Vobiz SIP → Phone Network → AI Conversation
```
{/* Prerequisites */}
## Prerequisites
Before starting:
→
**Retell AI Account** → [Sign up](https://dashboard.retellai.com)
→
**Vobiz Account** with SIP trunk → [Create account](https://console.vobiz.ai/auth/signup)
→
**Retell AI Agent** created → [Create in dashboard](https://dashboard.retellai.com/agents)
→
**Phone number** from Vobiz (for caller ID)
{/* Step 1 */}
## Step 1: Open Phone Numbers Section
- Log in to [Retell Dashboard](https://dashboard.retellai.com)
- Navigate to **Phone Numbers** in the sidebar
- Click the **"+"** button to add a new number
{/* Step 2 */}
## Step 2: Select SIP Trunking
Select **"Connect to your number via SIP trunking"**
This option allows you to use your own Vobiz phone number and SIP infrastructure instead of buying a number from Retell.
{/* Step 3 */}
## Step 3: Configure SIP Trunk
### Required Fields:
Phone Number
Your Vobiz phone number in E.164 format:
```
+1234567890
```
Include country code with `+` prefix
Termination URI
Your Vobiz SIP domain:
```
abc123.sip.vobiz.ai
```
⚠️ **Do NOT include** `sip:` prefix
SIP Trunk User Name (Optional)
Your Vobiz trunk username:
```
your_username
```
SIP Trunk Password (Optional)
Your Vobiz trunk password:
```
your_password
```
Nickname (Optional)
Friendly name for this number (e.g., "Vobiz Main Line")
**Where to get Vobiz credentials:**
- **Via Console:** [Vobiz Console](https://console.vobiz.ai) → Trunks → Your Trunk
- **Via API:** See [SIP Trunks Documentation](/trunks)
Click **Save** to complete the configuration.
Your phone number is now configured and ready for outbound calling!
{/* Step 4 */}
## Step 4: Make a Batch Call
- Click on your configured phone number
- Select **"Create a batch call"**
Fill in the details:
- **Batch Call Name:** Name for this campaign (e.g., "Customer Outreach")
- **From number:** Select your configured Vobiz number
- **Upload Recipients:** Upload CSV file with phone numbers
- **When to send:** Choose "Send Now" or "Schedule" for later
- Click **Send** or **Schedule**
Expected Behavior:
- Calls initiate to all numbers in CSV
- AI agent speaks when answered
- View call logs in Retell Dashboard
**CSV Format:**
For CSV file format and requirements, see [Retell Batch Calling Docs](https://docs.retellai.com)
Dashboard Setup Complete!
Your Retell AI agent can now make outbound calls through Vobiz SIP infrastructure. Perfect for testing and manual campaigns!
{/* Troubleshooting */}
## Troubleshooting
#### "Phone number not found"
**Problem:** Phone number not configured in Retell.
**Fix:**
- Verify number format is E.164 (`+countrycode + number`)
- Re-configure the phone number in Step 3
- Check number exists in [Vobiz Console](https://console.vobiz.ai)
#### Call fails immediately
**Problem:** SIP authentication or configuration issue.
**Fix:**
- Verify Vobiz username/password at [Vobiz Console](https://console.vobiz.ai)
- Must be exact Vobiz domain (e.g., `abc123.sip.vobiz.ai`)
- Do NOT include `sip:` prefix
- Try different transport type (TCP vs UDP) in trunk config
#### Insufficient Balance
**Problem:** Vobiz account has no credits.
**Fix:**
- Log in to [Vobiz Console](https://console.vobiz.ai) → Billing
- Add funds (minimum ₹100 recommended)
- See [Balance Documentation](/balance)
#### Agent doesn't speak
**Problem:** Agent not configured or not published.
**Fix:**
- Ensure agent is published in [Retell Dashboard → Agents](https://dashboard.retellai.com/agents)
- Check agent has voice configured
- Verify agent ID matches in phone number config
**Need more detailed troubleshooting?**
Check the [complete troubleshooting guide](/integrations/retellai-api#troubleshooting) in the API documentation for more error scenarios and solutions.
{/* Next Steps */}
## Next Steps
→
**Customize your agent**
Configure voice, personality, and prompts in [Retell Dashboard → Agents](https://dashboard.retellai.com/agents)
→
**View call analytics**
Monitor call logs and transcripts in Retell Dashboard → Calls
→
**Automate with API**
Learn to trigger calls programmatically in the [API Setup Guide](/integrations/retellai-api)
→
**Monitor usage**
Track Vobiz [balance](/balance) and [call records](/cdr)
{/* Navigation */}
);
}

---

# Page: /integrations/retellai-api

const tableOfContents = [
{ id: 'overview', title: 'Overview', level: 2 },
{ id: 'prerequisites', title: 'Prerequisites', level: 2 },
{ id: 'step-1', title: 'Step 1: Get API Key', level: 2 },
{ id: 'step-2', title: 'Step 2: List Agents', level: 2 },
{ id: 'step-3', title: 'Step 3: Configure Phone Number', level: 2 },
{ id: 'step-4', title: 'Step 4: Make Outbound Call', level: 2 },
{ id: 'troubleshooting', title: 'Troubleshooting', level: 2 },
{ id: 'quick-reference', title: 'Quick Reference', level: 2 }
];
return (
{/* Header */}
# Retell AI - API Setup
Programmatically integrate Retell AI with Vobiz using REST API and curl commands for automated calling.
**Prefer visual dashboard?**
Check out the [Dashboard Setup Guide](/integrations/retellai-dashboard) for a no-code integration method.
{/* Overview */}
## Overview
This guide shows how to integrate Retell AI with Vobiz using the API for **automated outbound calling**. Perfect for developers building applications that trigger AI calls programmatically.
Call flow:
```
Your App → Retell AI API → Vobiz SIP → Phone Network → AI Conversation
```
{/* Prerequisites */}
## Prerequisites
Before starting:
→
**Retell AI Account** → [Sign up](https://dashboard.retellai.com)
→
**Vobiz Account** with SIP trunk → [Create account](https://console.vobiz.ai/auth/signup)
→
**Retell AI Agent** created → [Create in dashboard](https://dashboard.retellai.com/agents)
→
**Phone number** from Vobiz (for caller ID)
**Get Vobiz Credentials:**
- **Via Console:** [Vobiz Console → Trunks](https://console.vobiz.ai)
- **Via API:** [Vobiz API Reference](/trunks)
{/* Step 1 */}
## Step 1: Get Your API Key
### Via Dashboard:
- Go to [Retell Dashboard → Settings → API Keys](https://dashboard.retellai.com/settings/api-keys)
- Click **Create API Key**
- Copy the key (starts with `key_`)
**⚠️ Keep this secret!**
Never commit to git or share publicly. Store securely in environment variables.
{/* Step 2 */}
## Step 2: List Available Agents
Retrieve all agents to get the `agent_id` you'll use for calls:
```
curl "https://api.retellai.com/list-agents" \\
-H "Authorization: Bearer key_abc123xyz789example"
```
#### Example Response:
```
[
{
"agent_id": "agent_abc123example",
"agent_name": "Customer Support Agent",
"voice_id": "11labs-Rachel",
"language": "en-US"
}
]
```
**What to extract:**
- `agent_id` - Use this when making calls
- `agent_name` - Human-readable name
- `voice_id` - Which voice the agent uses
📝 Copy the `agent_id` for the agent you want to use.
{/* Step 3 */}
## Step 3: Configure Phone Number with SIP Trunk
Add your Vobiz phone number and SIP trunk configuration to Retell:
```
curl "https://api.retellai.com/create-phone-number" \\
-X POST \\
-H "Authorization: Bearer key_abc123xyz789example" \\
-H "Content-Type: application/json" \\
-d '{
"phone_number": "+1234567890",
"phone_number_type": "custom",
"nickname": "Vobiz Main Line",
"outbound_agent_id": "agent_abc123example",
"sip_outbound_trunk_config": {
"termination_uri": "abc123.sip.vobiz.ai",
"transport": "TCP",
"auth_username": "your_username",
"auth_password": "your_password"
}
}'
```
#### Required Fields:
`phone_number`
Your Vobiz number in E.164 format: `+countrycode + number`
`phone_number_type`
Must be `"custom"` for SIP trunks
`outbound_agent_id`
Agent ID from Step 2
`sip_outbound_trunk_config`
- `termination_uri` - Vobiz SIP domain (without `sip:` prefix)
- `transport` - `"TCP"` (recommended)
- `auth_username` - Vobiz trunk username
- `auth_password` - Vobiz trunk password
**Get Vobiz credentials:**
[Vobiz Console](https://console.vobiz.ai) → Trunks → Your Trunk
✓ Use this number as `from_number` when making calls
{/* Step 4 */}
## Step 4: Make an Outbound Call
Trigger an AI call programmatically:
```
curl "https://api.retellai.com/v2/create-phone-call" \\
-X POST \\
-H "Authorization: Bearer key_abc123xyz789example" \\
-H "Content-Type: application/json" \\
-d '{
"from_number": "+1234567890",
"to_number": "+10987654321",
"agent_id": "agent_abc123example"
}'
```
#### Required Parameters:
`from_number`
Your configured Vobiz number (caller ID)
`to_number`
Destination number to call (E.164 format)
`agent_id`
Which agent to use for the call
#### Example Response:
```
{
"call_id": "call_abc123xyz789",
"call_status": "registered",
"from_number": "+1234567890",
"to_number": "+10987654321",
"direction": "outbound"
}
```
**What to extract:**
- `call_id` - Use this to retrieve call details later
`call_status` - Tracks call progress:
- `"registered"` → Call initiated
- `"ringing"` → Phone is ringing
- `"ongoing"` → Call connected
- `"ended"` → Call finished
Call initiated!
The destination phone will ring, and when answered, the AI agent will speak.
{/* Troubleshooting */}
## Troubleshooting
#### "401 Unauthorized"
**Cause:** Invalid API key
**Fix:**
- Verify API key in [Retell Dashboard → Settings](https://dashboard.retellai.com/settings/api-keys)
- Ensure it starts with `key_`
#### "Phone number not found"
**Cause:** Phone number not configured in Retell
**Fix:**
- Run Step 3 to add phone number with SIP trunk
- Verify number format is E.164 (`+countrycode + number`)
#### Call fails immediately
**Possible causes:**
1. Wrong SIP credentials
- Verify Vobiz username/password at [Vobiz Console](https://console.vobiz.ai)
2. Wrong transport type
- Try `"UDP"` instead of `"TCP"` in trunk config
3. SIP domain incorrect
- Must be exact Vobiz domain (e.g., `abc123.sip.vobiz.ai`)
- Do NOT include `sip:` prefix
4. Insufficient balance
- Check Vobiz account has credits at [Vobiz Console](https://console.vobiz.ai)
- See [Balance Documentation](/balance)
#### Agent doesn't speak
**Cause:** Agent not configured or not published
**Fix:**
- Ensure agent is published in [Retell Dashboard → Agents](https://dashboard.retellai.com/agents)
- Check agent has voice configured
- Verify agent ID matches in phone number config
{/* Quick Reference */}
## Quick Reference
### API Endpoints
Endpoint
Method
Purpose
`/list-agents`
GET
List all agents
`/list-phone-numbers`
GET
List configured numbers
`/create-phone-number`
POST
Add phone number with SIP trunk
`/v2/create-phone-call`
POST
Make outbound call
`/get-call/{'{call_id}'}`
GET
Get call details
**Base URL:** `https://api.retellai.com`
**Authentication:** `Authorization: Bearer YOUR_API_KEY`
### Complete Call Flow (curl)
```
# 1. List agents
curl "https://api.retellai.com/list-agents" \\
-H "Authorization: Bearer key_YOUR_KEY_HERE"
# 2. Configure phone number (one-time)
curl "https://api.retellai.com/create-phone-number" \\
-X POST \\
-H "Authorization: Bearer key_YOUR_KEY_HERE" \\
-H "Content-Type: application/json" \\
-d '{
"phone_number": "+1234567890",
"phone_number_type": "custom",
"outbound_agent_id": "agent_YOUR_AGENT_ID",
"sip_outbound_trunk_config": {
"termination_uri": "abc123.sip.vobiz.ai",
"transport": "TCP",
"auth_username": "your_username",
"auth_password": "your_password"
}
}'
# 3. Make a call
curl "https://api.retellai.com/v2/create-phone-call" \\
-X POST \\
-H "Authorization: Bearer key_YOUR_KEY_HERE" \\
-H "Content-Type: application/json" \\
-d '{
"from_number": "+1234567890",
"to_number": "+10987654321",
"agent_id": "agent_YOUR_AGENT_ID"
}'
```
#### Support Resources
- → [Retell AI Documentation](https://docs.retellai.com)
- → [Retell AI Dashboard](https://dashboard.retellai.com)
- → [Vobiz Documentation](/)
- → [Vobiz Console](https://console.vobiz.ai)
Integration complete!
Your Retell AI agents can now make outbound calls through Vobiz programmatically. Perfect for automated campaigns and application integrations!
{/* Navigation */}
);
}

---

# Page: /concepts

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'available-concepts', title: 'Available Concepts', level: 2 }
];
const concepts = [
{
title: 'Callbacks',
href: '/concepts/callbacks',
icon: HiOutlineDocumentText,
description: 'Understand how callbacks and webhooks work in Vobiz. Learn about callback URLs, event notifications, and real-time communication patterns.'
},
{
title: 'Callback Configurations',
href: '/concepts/callback-configurations',
icon: HiOutlineCog,
description: 'Configure callback endpoints for your applications. Set up URL endpoints, handle authentication, and manage callback parameters.'
}
];
return (
{/* Header Section */}
# Concepts
Learn core concepts and architectural patterns that power Vobiz telephony services. Understand how different components work together to build robust communication systems.
### What You'll Learn
- How callbacks and webhooks enable real-time event notifications
- Configuration patterns for callback URLs and authentication
- Best practices for handling asynchronous events
- Security considerations for webhook endpoints
{/* Available Concepts */}
## Available Concepts
{concepts.map((concept) => {
const IconComponent = concept.icon;
return (
{concept.title}
{concept.description}
);
})}
{/* Previous/Next Navigation */}
);
}

---

# Page: /concepts/callbacks

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'how-callbacks-work', title: 'How Callbacks Work', level: 2 },
{ id: 'callback-events', title: 'Callback Events', level: 2 },
{ id: 'callback-parameters', title: 'Callback Parameters', level: 2 },
{ id: 'security', title: 'Security Considerations', level: 2 },
{ id: 'best-practices', title: 'Best Practices', level: 2 }
];
return (
{/* Header Section */}
# Callbacks
Callbacks (also known as webhooks) are HTTP requests that Vobiz sends to your server to notify you about events in real-time. They enable asynchronous communication and event-driven architectures.
### What Are Callbacks?
When events occur in your Vobiz account (such as a call completing, a recording finishing, or a conference ending), Vobiz can automatically send HTTP POST requests to your server with detailed information about the event.
This allows your application to react to events in real-time without constantly polling our API for updates.
{/* How Callbacks Work */}
## How Callbacks Work
#### The Callback Flow
1
Configure Callback URL
You provide a callback URL when creating resources (applications, trunks, calls, etc.)
2
Event Occurs
An event happens in your account (call ends, recording completes, etc.)
3
Vobiz Sends HTTP POST
Vobiz sends an HTTP POST request to your callback URL with event details
4
Your Server Responds
Your server processes the callback and responds with HTTP 200 OK
#### Example Callback Request
When a call ends, Vobiz sends a POST request to your callback URL:
```
POST /webhooks/call-status HTTP/1.1
Host: your-domain.com
Content-Type: application/x-www-form-urlencoded
User-Agent: Vobiz-Webhook/1.0
{
"Event": "Hangup",
"CallUUID": "550e8400-e29b-41d4-a716-446655440000",
"From": "+14155551234",
"To": "+14155555678",
"Status": "completed",
"Duration": 125,
"StartTime": "2025-10-30T10:30:00Z",
"EndTime": "2025-10-30T10:32:05Z",
"Direction": "outbound",
"AccountId": "{Auth_ID}"
}
```
#### Example Server Response
Your server should respond with HTTP 200 to acknowledge receipt:
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "received"
}
```
{/* Callback Events */}
## Callback Events
Event Type
Description
When It's Sent
Ring
Call is ringing
When outbound call starts ringing (via /answer)
StartApp
Call was answered
When the called party answers (via /answer)
Hangup
Call has ended
When call completes (via /answer)
recording.completed
Recording is ready
When recording finishes processing
conference.started
Conference has started
When first participant joins
conference.ended
Conference has ended
When last participant leaves
{/* Callback Parameters */}
## Callback Parameters
#### Standard Parameters
All callback requests include these standard parameters:
Parameter
Type
Description
Event
string
Event type identifier (e.g., Ring, StartApp, Hangup)
timestamp
string
ISO 8601 timestamp of when event occurred
account_id
string
Your Vobiz account identifier
CallUUID
string
Unique identifier for the call
{/* Security Considerations */}
## Security Considerations
#### Always Use HTTPS
**Important:** Only use HTTPS URLs for callback endpoints. HTTP URLs are not supported for security reasons.
#### Verify Callback Source
Implement verification to ensure callbacks are genuinely from Vobiz:
```
const crypto = require('crypto');
function verifyCallback(request, secret) {
const signature = request.headers['x-vobiz-signature'];
const timestamp = request.headers['x-vobiz-timestamp'];
const body = JSON.stringify(request.body);
// Verify timestamp is recent (within 5 minutes)
const now = Date.now();
if (Math.abs(now - timestamp) > 5 * 60 * 1000) {
return false;
}
// Verify signature
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(timestamp + '.' + body)
.digest('hex');
return signature === expectedSignature;
}
```
#### Implement Replay Protection
Store processed callback IDs to prevent replay attacks:
- Check if callback ID has been processed before
- Store callback IDs in cache/database for 24 hours
- Reject duplicate callbacks with same ID
{/* Best Practices */}
## Best Practices
### Respond Quickly
Return HTTP 200 within 3 seconds. If processing takes longer, queue the callback for async processing and respond immediately.
### Handle Retries
Vobiz will retry failed callbacks (non-200 responses) up to 3 times with exponential backoff. Make your callback handlers idempotent to handle duplicate deliveries.
### Log Everything
Log all incoming callbacks with full payload for debugging. Include timestamps, event types, and processing results.
### Monitor Callback Health
Track callback success/failure rates, response times, and set up alerts for failures. Monitor for missing callbacks as a sign of delivery issues.
### Use Separate Endpoints
Consider using different callback URLs for different event types or resources to simplify routing and processing logic.
{/* Previous/Next Navigation */}
);
}

---

# Page: /concepts/callback-configurations

'use client';
const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'configuring-callbacks', title: 'Configuring Callbacks', level: 2 },
{ id: 'application-callbacks', title: 'Application Callbacks', level: 2 },
{ id: 'trunk-callbacks', title: 'Trunk Callbacks', level: 2 },
{ id: 'call-callbacks', title: 'Call Callbacks', level: 2 },
{ id: 'callback-authentication', title: 'Callback Authentication', level: 2 },
{ id: 'testing-callbacks', title: 'Testing Callbacks', level: 2 }
];
return (
{/* Header Section */}
# Callback Configurations
Learn how to configure callback URLs across different Vobiz resources. Set up endpoints to receive real-time event notifications for calls, conferences, recordings, and more.
### Quick Setup
Callbacks can be configured at multiple levels: account-wide defaults, per-application, per-trunk, or per-call. More specific configurations override broader ones.
{/* Configuring Callbacks */}
## Configuring Callbacks
#### Callback URL Requirements
- ✓ Must use HTTPS (not HTTP)
- ✓ Must be publicly accessible (not localhost)
- ✓ Must respond within 3 seconds
- ✓ Must return HTTP 200 status code
- ✓ Should handle POST requests
- ✓ Should accept application/x-www-form-urlencoded content type (form data)
#### Callback Configuration Hierarchy
Callbacks are resolved in this order (most specific to least specific):
1
Per-Call Callback
Callback URL specified when making a call
status_url parameter in Make Call API
2
Application Callback
Callback configured in Application settings
callback_url in Application object
3
Trunk Callback
Callback configured on SIP Trunk
status_callback in Trunk configuration
4
Account Default
Account-wide default callback URL
default_callback_url in Account settings
{/* Application Callbacks */}
## Application Callbacks
#### Configure Application Callback
Set up callbacks when creating or updating an application:
```
POST /api/v1/account/{account_id}/applications/
{
"name": "Customer Support App",
"callback_url": "https://api.yourapp.com/webhooks/vobiz/calls",
"callback_method": "POST",
"fallback_callback_url": "https://backup.yourapp.com/webhooks/vobiz/calls",
"callback_events": [
"Ring",
"StartApp",
"Hangup",
"recording.completed"
]
}
```
#### Application Callback Parameters
{/* Trunk Callbacks */}
## Trunk Callbacks
#### Configure Trunk Status Callback
Receive callbacks for all calls through a specific trunk:
```
PUT /api/v1/account/{account_id}/trunks/{trunk_id}
{
"status_callback": "https://api.yourapp.com/webhooks/trunk-events",
"status_callback_method": "POST",
"status_callback_events": [
"Ring",
"StartApp",
"Hangup",
"call.failed"
]
}
```
#### Trunk Callback Use Cases
- **Call Tracking:** Monitor all calls through a specific trunk
- **Department Routing:** Different callbacks for sales vs support trunks
- **Billing Integration:** Track usage per trunk for chargeback
- **Quality Monitoring:** Collect metrics for specific carriers/trunks
{/* Call Callbacks */}
## Call-Level Callbacks
#### Per-Call Callback Configuration
Override application/trunk callbacks for specific calls:
```
POST /api/v1/account/{account_id}/calls/
{
"from": "+14155551234",
"to": "+14155555678",
"answer_url": "https://api.yourapp.com/xml/call-flow",
"status_url": "https://api.yourapp.com/webhooks/important-call",
"status_method": "POST",
"status_callback_events": [
"Ring",
"StartApp",
"Hangup"
]
}
```
#### When to Use Call-Level Callbacks
- • High-priority calls that need special tracking
- • A/B testing different callback handlers
- • Customer-specific webhook endpoints
- • Temporary overrides for debugging
{/* Callback Authentication */}
## Callback Authentication
#### Basic Authentication
Include credentials in the callback URL:
```
https://username:password@api.yourapp.com/webhooks/vobiz
```
**Note:** While this works, we recommend using signature verification instead of basic auth for better security.
#### Signature Verification (Recommended)
Verify callbacks using HMAC signatures:
```
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());
const WEBHOOK_SECRET = process.env.VOBIZ_WEBHOOK_SECRET;
function verifySignature(req) {
const signature = req.headers['x-vobiz-signature'];
const timestamp = req.headers['x-vobiz-timestamp'];
if (!signature || !timestamp) {
return false;
}
// Verify timestamp is recent (within 5 minutes)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - timestamp) > 300) {
return false;
}
// Compute expected signature
const payload = timestamp + '.' + JSON.stringify(req.body);
const expectedSignature = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
app.post('/webhooks/vobiz/calls', (req, res) => {
// Verify signature
if (!verifySignature(req)) {
return res.status(401).json({ error: 'Invalid signature' });
}
// Process callback
const event = req.body.Event;
const callId = req.body.CallUUID;
console.log(\`Received \${event} for call \${callId}\`);
// Queue for async processing
queueCallback(req.body);
// Respond immediately
res.status(200).json({ status: 'received' });
});
```
#### Custom Headers
Add custom headers to callback requests for additional authentication:
```
{
"callback_url": "https://api.yourapp.com/webhooks/vobiz",
"callback_headers": {
"X-API-Key": "your-secret-api-key",
"X-Application-ID": "app-12345"
}
}
```
{/* Testing Callbacks */}
## Testing Callbacks
### Use webhook.site for Quick Testing
For development and testing, use services like webhook.site to inspect callback payloads:
- Visit https://webhook.site and copy your unique URL
- Configure this URL as your callback URL
- Trigger events (make calls, etc.)
- Inspect callback payloads in webhook.site UI
### Local Development with ngrok
Test callbacks on your local machine using ngrok:
```
# Install ngrok
npm install -g ngrok
# Start your local server (e.g., port 3000)
node server.js
# Create public tunnel
ngrok http 3000
# Use the ngrok HTTPS URL as your callback URL
# Example: https://abc123.ngrok.io/webhooks/vobiz
```
### Test Callback Handler
Create a simple test to verify your callback handler works:
```
const axios = require('axios');
async function testCallback() {
const mockCallbackData = {
Event: 'Hangup',
CallUUID: 'test-call-123',
From: '+14155551234',
To: '+14155555678',
Status: 'completed',
Duration: 125,
AccountId: 'MA_TEST123'
};
try {
const response = await axios.post(
'https://yourdomain.com/webhooks/vobiz/calls',
new URLSearchParams(mockCallbackData).toString(),
{
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'User-Agent': 'Vobiz-Webhook/1.0'
}
}
);
console.log('✓ Callback handler responded:', response.status);
} catch (error) {
console.error('✗ Callback handler failed:', error.message);
}
}
testCallback();
```
### Monitor Callback Delivery
Set up monitoring and alerting for callback failures: • Track callback success/failure rates • Alert on consecutive failures (3+) • Monitor callback response times • Log all callback attempts with outcomes
{/* Previous/Next Navigation */}
);
}

---

# Page: /integrations

const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'supported-platforms', title: 'Supported Platforms', level: 2 },
{ id: 'prerequisites', title: 'Prerequisites', level: 2 },
{ id: 'getting-started', title: 'Getting Started', level: 2 }
];
const platforms = [
{
name: 'LiveKit',
href: '/integrations/livekit',
description: 'Connect Vobiz SIP trunks with LiveKit for real-time voice and video applications. Build scalable WebRTC solutions with seamless SIP integration.'
},
{
name: 'ElevenLabs Agent',
href: '/integrations/elevenlabs-dashboard',
description: 'Integrate ElevenLabs conversational AI agents with Vobiz SIP infrastructure for natural voice interactions and intelligent call handling.'
},
{
name: 'VAPI',
href: '/integrations/vapi-dashboard',
description: 'Connect VAPI voice AI platform to Vobiz SIP trunks for building voice-driven applications and automated phone systems.'
},
{
name: 'Retell AI',
href: '/integrations/retellai-dashboard',
description: 'Integrate Retell AI conversational agents with Vobiz SIP infrastructure for natural AI phone conversations and automated outbound campaigns.'
},
{
name: 'Pipecat',
href: '/integrations/pipecat',
description: 'Build AI-powered voice agents with Vobiz telephony and Pipecat framework. Real-time AI conversations powered by OpenAI (STT → LLM → TTS).'
}
];
return (
{/* Header Section */}
# Integrations
Connect Vobiz SIP trunking with leading AI voice platforms and communication tools. Follow our step-by-step guides to integrate your favorite platforms with Vobiz infrastructure.
{/* Supported Platforms */}
## Supported Platforms
{platforms.map((platform) => (
{platform.name}
{platform.description}
View Integration Guide →
))}
{/* Prerequisites */}
## Prerequisites
Before integrating with any platform, ensure you have the following:
1
#### Vobiz Account
Create a Vobiz account via the API. You'll need your `account_id` and API credentials.
2
#### SIP Trunk
Create a SIP trunk for your account. You'll receive a unique SIP domain like `trk_abc123.sip.vobiz.ai`.
3
#### Account Balance
Add funds to your account to enable outbound calls and number provisioning. Check the Balance & Billing section for details.
4
#### Platform Account
Sign up for an account on your chosen integration platform (LiveKit, ElevenLabs, VAPI, Retell AI, etc.) and obtain necessary API keys.
{/* Getting Started */}
## Getting Started
#### Step 1: Choose Your Platform
Select one of the supported platforms above based on your use case. Each platform offers different capabilities for voice AI, WebRTC, and conversational interfaces.
#### Step 2: Review Prerequisites
Make sure you have a Vobiz SIP trunk created and configured. You'll need the trunk's SIP domain, username, and authentication credentials.
#### Step 3: Follow Platform Guide
Click on any platform card above to access the detailed integration guide. Each guide includes step-by-step instructions, code examples, and troubleshooting tips.
#### Step 4: Test Your Integration
After configuration, test your integration with a sample call. Verify CDRs are being logged and balance is being debited correctly.
#### Need Help?  Each integration guide includes a troubleshooting section. You can also refer to our Error Handling documentation for common issues and solutions.
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /errors

const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'error-format', title: 'Error Response Format', level: 2 },
{ id: 'http-codes', title: 'HTTP Status Codes', level: 2 },
{ id: 'common-errors', title: 'Common Errors', level: 2 },
{ id: 'validation-errors', title: 'Validation Errors', level: 2 },
{ id: 'troubleshooting', title: 'Troubleshooting Guide', level: 2 }
];
return (
{/* Header Section */}
# Error Handling
Understand API error responses, status codes, and how to handle common error scenarios in your integration. All errors follow a consistent format for easy parsing and debugging.
{/* Error Response Format */}
## Error Response Format
All API errors follow a standardized JSON format for consistency across all services:
```
{
"status": "error",
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Account balance too low to complete this operation",
"details": {
"required": 1000,
"available": 450,
"currency": "USD"
}
},
"timestamp": "2025-10-12T10:30:00.000Z",
"requestId": "req_7a8b9c0d1e2f"
}
```
#### Response Fields
- `status` - Always "error" for error responses
- `error.code` - Machine-readable error code (uppercase, underscore-separated)
- `error.message` - Human-readable error description
- `error.details` - Additional context (optional, varies by error)
- `timestamp` - When the error occurred
- `requestId` - Unique request identifier for support/debugging
{/* HTTP Status Codes */}
## HTTP Status Codes
#### 2xx Success
- **200 OK** - Request successful, response contains data
- **201 Created** - Resource created successfully (e.g., trunk, sub-account)
- **204 No Content** - Request successful, no response body (e.g., DELETE operations)
#### 4xx Client Errors
- **400 Bad Request** - Invalid request format or parameters
- **401 Unauthorized** - Missing or invalid authentication credentials
- **402 Payment Required** - Insufficient account balance
- **403 Forbidden** - Authenticated but lacking permission for this resource
- **404 Not Found** - Requested resource does not exist
- **409 Conflict** - Request conflicts with current state (e.g., duplicate username)
- **422 Unprocessable Entity** - Validation failed (see details for field errors)
- **429 Too Many Requests** - Rate limit exceeded
#### 5xx Server Errors
- **500 Internal Server Error** - Unexpected server error (report via requestId)
- **502 Bad Gateway** - Downstream service unavailable
- **503 Service Unavailable** - Service temporarily down or overloaded
- **504 Gateway Timeout** - Downstream service timeout
{/* Common Errors */}
## Common Errors
{/* Authentication Errors */}
#### Authentication Errors
INVALID_CREDENTIALS
Status: 401 | Email/password combination incorrect
```
{
"status": "error",
"error": {
"code": "INVALID_CREDENTIALS",
"message": "Invalid email or password"
}
}
```
TOKEN_EXPIRED
Status: 401 | Access token has expired (use refresh token)
```
{
"status": "error",
"error": {
"code": "TOKEN_EXPIRED",
"message": "Access token has expired. Use refresh token to obtain a new one."
}
}
```
ACCOUNT_INACTIVE
Status: 403 | Account has been deactivated
```
{
"status": "error",
"error": {
"code": "ACCOUNT_INACTIVE",
"message": "Account is inactive. Contact support to reactivate."
}
}
```
{/* Resource Errors */}
#### Resource Errors
TRUNK_NOT_FOUND
Status: 404 | Trunk ID does not exist or belongs to different account
```
{
"status": "error",
"error": {
"code": "TRUNK_NOT_FOUND",
"message": "SIP trunk not found",
"details": {
"trunkId": "TRK_invalid123"
}
}
}
```
DUPLICATE_USERNAME
Status: 409 | Trunk username already exists
```
{
"status": "error",
"error": {
"code": "DUPLICATE_USERNAME",
"message": "Username already exists",
"details": {
"username": "mytrunk",
"suggestion": "Try mytrunk2 or mytrunk_2025"
}
}
}
```
{/* Balance Errors */}
#### Balance & Billing Errors
INSUFFICIENT_BALANCE
Status: 402 | Account balance too low
```
{
"status": "error",
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Insufficient balance to purchase phone number",
"details": {
"required": 1000,
"available": 450,
"currency": "USD",
"shortfall": 550
}
}
}
```
PAYMENT_FAILED
Status: 402 | Payment processing failed
```
{
"status": "error",
"error": {
"code": "PAYMENT_FAILED",
"message": "Payment declined by gateway",
"details": {
"gateway": "razorpay",
"reason": "Insufficient funds in linked account"
}
}
}
```
{/* Rate Limiting */}
#### Rate Limiting Errors
RATE_LIMIT_EXCEEDED
Status: 429 | Too many requests or calls
```
{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "CPS limit exceeded for this trunk",
"details": {
"limitType": "cps",
"limit": 10,
"current": 15,
"retryAfter": 1
}
}
}
```
{/* Validation Errors */}
## Validation Errors
When request validation fails (422 status), the response includes detailed field-level errors:
```
{
"status": "error",
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": {
"errors": [
{
"field": "password",
"message": "Password must be at least 8 characters",
"code": "MIN_LENGTH",
"value": "abc"
},
{
"field": "email",
"message": "Invalid email format",
"code": "INVALID_FORMAT",
"value": "notanemail"
},
{
"field": "maxCps",
"message": "Must be between 1 and 1000",
"code": "OUT_OF_RANGE",
"value": 5000
}
]
}
}
}
```
#### Handling Validation Errors
Parse the `details.errors` array to display field-specific error messages in your UI. Each error includes the field name, error code, and the invalid value.
{/* Troubleshooting Guide */}
## Troubleshooting Guide
### Check HTTP Status Code First
The status code category tells you who's at fault: 4xx = client error (fix your request), 5xx = server error (retry or contact support).
### Always Log requestId
Save the `requestId` from error responses. When contacting support, provide this ID for faster debugging and resolution.
### Implement Exponential Backoff
For 429 (rate limit) and 503 (service unavailable) errors, retry with exponential backoff: wait 1s, then 2s, then 4s, etc. Check `Retry-After` header if present.
### Validate Before Sending
Implement client-side validation matching API requirements to catch errors before making requests. Reduces unnecessary API calls and improves user experience.
### Monitor Error Rates
Track error response counts and types over time. Sudden spikes in specific error codes may indicate configuration issues or API changes requiring attention.
### Common 401 Fixes
• Ensure `X-Auth-ID` and `X-Auth-Token` headers are included • Check token hasn't expired • Verify account is active (`is_active=true`)
{/* Previous/Next Page Navigation */}
);
}

---

# Page: /best-practices

const tableOfContents = [
{ id: 'introduction', title: 'Introduction', level: 2 },
{ id: 'security', title: 'Security Best Practices', level: 2 },
{ id: 'authentication', title: 'Authentication & Authorization', level: 2 },
{ id: 'performance', title: 'Performance Optimization', level: 2 },
{ id: 'reliability', title: 'Reliability & Error Handling', level: 2 },
{ id: 'monitoring', title: 'Monitoring & Logging', level: 2 },
{ id: 'testing', title: 'Testing Strategies', level: 2 }
];
return (
{/* Header Section */}
# Best Practices
Follow these recommendations for secure, reliable, and performant integrations with Vobiz. Learn from our experience and avoid common pitfalls.
{/* Security Best Practices */}
## Security Best Practices
#### Never Hardcode Credentials
❌ Bad Practice
```
const API_KEY = "sk_live_abc123def456";  // NEVER DO THIS
const PASSWORD = "my_secret_password";    // NEVER DO THIS
```
✅ Good Practice
```
// Load from environment variables
const API_KEY = process.env.VOBIZ_API_KEY;
const PASSWORD = process.env.VOBIZ_PASSWORD;
// Or use a secrets manager
const secrets = await secretsManager.getSecret("vobiz/credentials");
```
#### Use HTTPS for All Requests
Always use `https://` URLs when calling the API. Never send authentication tokens or sensitive data over unencrypted HTTP connections. Our API only responds to HTTPS.
#### Rotate Credentials Regularly
- Change trunk passwords every 90 days
- Change account passwords regularly and invalidate old refresh tokens
- Immediately rotate if credentials are suspected to be compromised
- Use sub-accounts for different applications/teams to limit blast radius
#### Whitelist IP Addresses
For production SIP trunks with static IPs, use IP authentication instead of passwords:
```
{
"authType": "ip",
"ipWhitelist": [
"203.0.113.10",  // Production PBX
"203.0.113.11"   // Backup PBX
]
}
```
This eliminates password-based attacks and simplifies configuration for trusted systems.
#### Validate Input on Client Side
Implement client-side validation before sending requests to prevent injection attacks:
- Sanitize phone numbers (remove special characters, validate E.164 format)
- Validate email addresses match RFC 5322 spec
- Limit string lengths (trunk names, usernames, etc.)
- Reject suspicious patterns (SQL injection attempts, XSS payloads)
{/* Authentication & Authorization */}
## Authentication & Authorization
#### Token Storage
⚠️ Frontend Applications
- Store access tokens in memory or sessionStorage (expires when tab closes)
- Never store tokens in localStorage (vulnerable to XSS attacks)
- Use httpOnly cookies for refresh tokens if possible
✅ Backend Applications
- Store tokens in environment variables or secrets manager
- Encrypt tokens at rest if storing in database
- Use secure memory storage for short-lived tokens
#### Automatic Token Refresh
Implement automatic token refresh before expiration (30 minutes for access tokens):
```
async function makeAuthenticatedRequest(url, options) {
// Check if token expires in next 5 minutes
if (tokenExpiresAt - Date.now()
#### Use Sub-Accounts for Separation
Create separate sub-accounts for different applications, environments, or teams:
- **Development:** Separate sub-account for testing
- **Production:** Dedicated sub-account with stricter controls
- **Partners:** Sub-accounts for each integration partner
- **Departments:** Sales, Support, Engineering teams get own sub-accounts
{/* Performance Optimization */}
## Performance Optimization
#### Implement Caching
Cache infrequently changing data to reduce API calls:
Resource
Cache TTL
Notes
Account info
15 minutes
Rarely changes
Trunk list
5 minutes
Invalidate on create/delete
Balance
1 minute
Frequently updated
CDRs
No cache
Always fetch fresh
#### Use Pagination Wisely
Don't fetch all records at once. Use pagination for large datasets:
```
// Fetch CDRs in batches of 100
async function getAllCDRs(accountId, startDate, endDate) {
const allCDRs = [];
let offset = 0;
const limit = 100;
while (true) {
const response = await fetch(
\`/api/v1/account/\${accountId}/cdr?start_date=\${startDate}&end_date=\${endDate}&limit=\${limit}&offset=\${offset}\`
);
const data = await response.json();
allCDRs.push(...data.data.cdrs);
if (!data.data.pagination.hasMore) break;
offset += limit;
}
return allCDRs;
}
```
#### Batch Operations
Instead of making multiple individual requests, consider implementing client-side batching:
- Batch CDR queries by date ranges instead of querying each day separately
- Combine multiple resource updates in a single transaction when possible
- Use bulk operations for importing/exporting large datasets
#### Connection Pooling
Reuse HTTP connections instead of creating new ones for every request:
```
const https = require('https');
// Create agent with connection pooling
const agent = new https.Agent({
keepAlive: true,
maxSockets: 50,
maxFreeSockets: 10,
timeout: 60000
});
// Reuse agent for all requests
fetch(url, { agent });
```
{/* Reliability & Error Handling */}
## Reliability & Error Handling
#### Implement Retry Logic
Retry failed requests with exponential backoff for transient errors:
```
async function fetchWithRetry(url, options, maxRetries = 3) {
for (let attempt = 0; attempt = 400 && response.status  setTimeout(resolve, delay));
} catch (error) {
if (attempt === maxRetries) throw error;
const delay = Math.pow(2, attempt) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
}
}
}
```
#### Circuit Breaker Pattern
Prevent cascading failures by implementing a circuit breaker:
- Track consecutive failures for each service
- After 5 failures, "open" circuit and fail fast for 30 seconds
- After timeout, allow one request through ("half-open" state)
- If successful, close circuit; if failed, reopen for longer
#### Handle Rate Limits Gracefully
When you receive a 429 (Rate Limit) response:
```
async function handleRateLimit(response) {
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After') || 60;
console.log(\`Rate limited. Retrying after \${retryAfter} seconds\`);
await new Promise(resolve =>
setTimeout(resolve, retryAfter * 1000)
);
// Retry the request
return fetch(url, options);
}
return response;
}
```
#### Idempotency Keys
For critical operations (purchases, transactions), use idempotency keys to prevent duplicates:
```
const idempotencyKey = \`purchase-\${Date.now()}-\${Math.random()}\`;
await fetch('/api/v1/account/ACC123/numbers/purchase', {
method: 'POST',
headers: {
'Idempotency-Key': idempotencyKey,
'Content-Type': 'application/json'
},
body: JSON.stringify({ phoneNumber: '+14155551234' })
});
```
{/* Monitoring & Logging */}
## Monitoring & Logging
#### Log All API Requests
Maintain detailed logs for debugging and auditing:
```
function logAPIRequest(method, url, status, duration, requestId) {
console.log({
timestamp: new Date().toISOString(),
method,
url,
status,
duration: \`\${duration}ms\`,
requestId,
service: 'vobiz-api'
});
}
```
#### Track Key Metrics
- • API request success/failure rates
- • Average response times per endpoint
- • Error distribution by error code
- • Token refresh frequency
- • Balance consumption rate
- • Call success rates (ASR)
- • Rate limit violations
#### Set Up Alerts
Configure alerts for critical events:
- **Balance Low:** Alert when balance drops below threshold
- **Error Spike:** Alert when error rate exceeds 5% of requests
- **Trunk Down:** Alert when trunk authentication fails repeatedly
- **Rate Limit Hit:** Alert when approaching rate limits
{/* Testing Strategies */}
## Testing Strategies
### Use Separate Accounts for Testing
Create dedicated test accounts/sub-accounts with separate credentials. Never test in production with real customer data or active trunks.
### Test Error Scenarios
Don't just test happy paths. Verify your application handles errors correctly: invalid credentials, insufficient balance, rate limits, network timeouts, etc.
### Automate Integration Tests
Use the Postman collection with Newman CLI in your CI/CD pipeline to catch integration regressions early. Run tests on every commit to main branch.
### Monitor Test Call Quality
Make regular test calls and verify: • Call connects within 3 seconds (low PDD) • Audio quality is clear (no packet loss) • CDR is generated correctly • Balance is debited accurately
### Load Testing
Before going live, test with realistic load: • Simulate expected CPS (calls per second) • Test concurrent call limits • Verify rate limiting behaves as expected • Monitor API response times under load
{/* Previous/Next Page Navigation */}
);
}