LiveKit + Vobiz Integration Guide

Connect your LiveKit AI voice agents to Vobiz SIP infrastructure for phone calling capabilities.

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:

Integration Flow

Outbound: Your App → LiveKit → Vobiz → Phone Network
Inbound:  Phone Network → Vobiz → LiveKit → AI Agent

Prerequisites

Before starting:

✅
Vobiz Account with active balance → Create account
✅
LiveKit Account with project → Sign up
✅
LiveKit AI Agent built → LiveKit Agents docs

Part 1: Vobiz Setup

Create SIP Trunk

Create a SIP trunk in Vobiz to handle voice traffic.

See: Vobiz SIP Trunks Documentation

⚠️ 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

Purchase a phone number for outbound caller ID or inbound calls.

See: Vobiz Phone Numbers Documentation

Part 2: LiveKit Setup

Get LiveKit Credentials

Go to LiveKit Cloud Dashboard
Select your project
Navigate to Settings → API Keys
Copy these values:

Credential	Where to Find
LIVEKIT_URL	Settings → General
LIVEKIT_API_KEY	Settings → API Keys
LIVEKIT_API_SECRET	Settings → API Keys

Example

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxxxxxxx
LIVEKIT_API_SECRET=secretxxxxxxxxxx

Part 3: Connect LiveKit to Vobiz (Outbound)

Initialize LiveKit API Client

Example Code: For a complete example of Outbound Caller, check the LiveKit Vobiz Outbound Repository.

Python

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

Connect LiveKit to your Vobiz SIP trunk:

Python

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

Python

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

Example Code: For a complete example of Inbound Caller, check the LiveKit Vobiz Inbound Repository.

Step 1: Get LiveKit SIP URI

Go to LiveKit Cloud Dashboard
Select your project
Go to Settings → Project
Find SIP URI field

Example

sip:your-sip-uri.sip.livekit.cloud

Step 2: Update Vobiz Trunk Inbound Destination

Update your Vobiz trunk to route calls to LiveKit.

See: Vobiz Update Trunk Documentation

⚠️ CRITICAL: Remove the sip: prefix when configuring Vobiz!

What LiveKit Shows	What to Enter in Vobiz
sip:your-sip-uri.sip.livekit.cloud	your-sip-uri.sip.livekit.cloud

API Example

PATCH https://api.vobiz.ai/api/v1/account/{accountId}/trunks/{trunkId}

JSON Request Body

{
  "inbound_destination": "your-sip-uri.sip.livekit.cloud"
}

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

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

This section outlines how to use the Cold Transfer (SIP REFER) functionality in the LiveKit Voice Agent.

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.

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

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 → Trunks
Ensure LiveKit trunk has matching credentials

Insufficient Balance

Check balance at Vobiz Console
Add funds if needed
See Vobiz Balance docs

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

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

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

Vobiz Documentation

LiveKit Documentation

Example Repositories

Support

Vobiz: support@vobiz.ai
LiveKit: livekit.io/support

Integration complete!

Your LiveKit agents can now make and receive calls through Vobiz.

Integrations

Error Handling

LiveKit + Vobiz Integration Guide

Overview

Prerequisites

Part 1: Vobiz Setup

Create SIP Trunk

Get Phone Number

Part 2: LiveKit Setup

Get LiveKit Credentials

Part 3: Connect LiveKit to Vobiz (Outbound)

Initialize LiveKit API Client

Create Outbound Trunk

Part 4: Make Outbound Calls

Part 5: Configure Inbound Calling

Step 1: Get LiveKit SIP URI

Step 2: Update Vobiz Trunk Inbound Destination

Step 3: Create LiveKit Inbound Trunk

Step 4: Create Dispatch Rule

Part 6: SIP Call Transfer

Performing a Transfer

Default Transfer

Custom Transfer

Transfer Troubleshooting

Troubleshooting

Outbound Calls

Call Doesn't Connect

SIP 401 Unauthorized

Insufficient Balance

Inbound Calls

Call Disconnects Immediately

Agent Doesn't Answer

Quick Reference

Required Credentials

Common Errors

Additional Resources

Vobiz Documentation

LiveKit Documentation

Example Repositories

Support

On this page