Vobiz Logo
Vobiz
|API Documentation
Console

SIP Trunk Management

Create and manage SIP trunks for enterprise telephony. Each trunk automatically gets a unique SIP domain, authentication credentials, and configurable codecs and rate limits.

Key Features

  • Auto-generated SIP domains: trunkId.sip.vobiz.ai
  • Kamailio integration for SIP routing and authentication
  • Support for password-based and IP-based authentication
  • Configurable codecs (G729, PCMU, PCMA), DTMF modes, rate limits
  • Real-time call tracking and channel management

Create SIP Trunk

POST/api/v1/account/{accountId}/trunks

Create a new SIP trunk. The system automatically generates a unique SIP domain and credentials. The trunk is immediately active and ready for calls.

▶HTTP Headers
Host:api.vobiz.ai
Content-Type:application/json
Authorization:Bearer {{accessToken}}

About This Endpoint

Provision a new SIP trunk that serves as your dedicated voice gateway for handling inbound and outbound telephony traffic. The platform automatically generates a unique SIP domain, secure authentication credentials, and registers the trunk with Kamailio SIP proxy infrastructure. You can configure codec preferences for voice quality optimization, set concurrent channel limits for capacity management, and define rate limiting to prevent billing spikes or abuse. The trunk activates immediately upon creation.

Key Capabilities
  • Auto-generates unique SIP domain following pattern trunkId.sip.vobiz.ai
  • Supports both password-based (digest) and IP-based authentication methods
  • Configurable codec preferences, DTMF modes, channel limits, and rate throttling
Production Considerations
  • Save the auto-generated password immediately—it cannot be retrieved after creation
  • Set max_channels based on expected concurrent call volume (typically 100-500)
  • Configure rate_limit (CPS) to prevent unexpected billing from traffic surges
Request Body
{
  "name": "US Primary",
  "username": "trunkuser",
  "password": "TrunkPassword123!",
  "concurrent_calls_limit": 20,
  "cps_limit": 10,
  "ip_whitelist": [
    "198.51.100.10"
  ],
  "description": "Primary outbound trunk"
}

Field Descriptions

FieldTypeRequiredDescription
namestringYesHuman-readable name for the trunk
usernamestringYesSIP username for authentication
passwordstringYesSIP password for authentication
concurrent_calls_limitintegerNoMaximum number of concurrent calls allowed on this trunk
cps_limitintegerNoCalls per second (CPS) rate limit to prevent traffic surges
ip_whitelistarrayNoArray of IP addresses allowed to use this trunk without password auth
descriptionstringNoOptional description for the trunk

Response Example

Success Response (201 Created)
{
  "id": "trunk_7a8b9c0d1e2f3g4h",
  "account_id": "MA_2210JXXN",
  "name": "Production SIP Trunk",
  "description": "Primary production trunk for company",
  "domain": "trunk_7a8b9c0d1e2f3g4h.sip.vobiz.ai",
  "username": "trunk_7a8b9c0d1e2f3g4h",
  "password": "auto_generated_secure_password_123",
  "auth_type": "password",
  "codec_preferences": ["G729", "PCMU", "PCMA"],
  "dtmf_mode": "rfc2833",
  "max_channels": 100,
  "current_channels": 0,
  "rate_limit": 1000,
  "status": "active",
  "created_at": "2025-10-12T10:00:00.000Z",
  "kamailio_registered": true
}

Success! Your trunk is now active with domain:trunk_7a8b9c0d1e2f3g4h.sip.vobiz.ai

List SIP Trunks

GET/api/v1/account/{accountId}/trunks

Retrieve all SIP trunks for your account with their current status and usage metrics.

▶HTTP Headers
Host:api.vobiz.ai
Authorization:Bearer {{accessToken}}

About This Endpoint

Retrieve a complete inventory of all SIP trunks provisioned under your account, including real-time operational metrics and status information. Each trunk entry includes current active channels, daily call statistics, configuration summary, and operational status. This endpoint is essential for monitoring trunk utilization across your infrastructure, identifying capacity bottlenecks, and auditing your SIP trunk deployment. The response provides a high-level overview ideal for dashboard displays and system health monitoring.

Included Metrics
  • Real-time concurrent channel usage vs maximum capacity for each trunk
  • Daily call volume statistics to track usage patterns and billing projections
  • Operational status indicating whether trunks are active, suspended, or inactive
Common Use Cases
  • Building admin dashboards that display all trunks with live usage statistics
  • Monitoring capacity utilization to determine when to scale or add new trunks
  • Generating trunk inventory reports for auditing and billing reconciliation

Response Example

Success Response (200 OK)
{
  "trunks": [
    {
      "id": "trunk_7a8b9c0d1e2f3g4h",
      "name": "Production SIP Trunk",
      "domain": "trunk_7a8b9c0d1e2f3g4h.sip.vobiz.ai",
      "status": "active",
      "max_channels": 100,
      "current_channels": 5,
      "total_calls_today": 1250,
      "created_at": "2025-10-12T10:00:00.000Z"
    },
    {
      "id": "trunk_8b9c0d1e2f3g4h5i",
      "name": "Backup SIP Trunk",
      "domain": "trunk_8b9c0d1e2f3g4h5i.sip.vobiz.ai",
      "status": "active",
      "max_channels": 50,
      "current_channels": 0,
      "total_calls_today": 0,
      "created_at": "2025-10-11T14:30:00.000Z"
    }
  ],
  "total": 2
}

Get Trunk Details

GET/api/v1/account/{accountId}/trunks/{trunkId}

Get detailed information about a specific trunk including credentials and configuration.

▶HTTP Headers
Host:api.vobiz.ai
Authorization:Bearer {{accessToken}}

About This Endpoint

Fetch comprehensive details for a specific SIP trunk including full configuration parameters, authentication credentials, real-time channel usage, and historical call statistics. This endpoint returns all trunk properties including codec preferences, DTMF settings, rate limits, and operational metrics. The response includes detailed statistics such as total calls processed, cumulative call duration, average call length, and peak concurrent usage—valuable data for capacity planning and performance analysis.

Detailed Information Provided
  • Complete SIP authentication credentials (username, password, domain) for client configuration
  • Full configuration including codecs, DTMF mode, channel limits, and rate throttling
  • Comprehensive statistics: total calls, duration, averages, and peak usage metrics
Common Use Cases
  • Retrieving SIP credentials after initial setup for client reconfiguration
  • Analyzing historical statistics for capacity planning and infrastructure scaling
  • Auditing trunk configuration before making updates or troubleshooting issues

Response Example

Success Response (200 OK)
{
  "id": "trunk_7a8b9c0d1e2f3g4h",
  "account_id": "MA_2210JXXN",
  "name": "Production SIP Trunk",
  "description": "Primary production trunk for company",
  "domain": "trunk_7a8b9c0d1e2f3g4h.sip.vobiz.ai",
  "username": "trunk_7a8b9c0d1e2f3g4h",
  "password": "auto_generated_secure_password_123",
  "auth_type": "password",
  "codec_preferences": ["G729", "PCMU", "PCMA"],
  "dtmf_mode": "rfc2833",
  "max_channels": 100,
  "current_channels": 5,
  "rate_limit": 1000,
  "status": "active",
  "statistics": {
    "total_calls": 125000,
    "total_duration_minutes": 450000,
    "average_call_duration": 3.6,
    "calls_today": 1250,
    "peak_concurrent_calls": 45
  },
  "created_at": "2025-10-12T10:00:00.000Z",
  "updated_at": "2025-10-12T16:30:00.000Z"
}

Update SIP Trunk

PUT/api/v1/account/{accountId}/trunks/{trunkId}

Update trunk configuration such as name, max channels, rate limits, or status.

▶HTTP Headers
Host:api.vobiz.ai
Content-Type:application/json
Authorization:Bearer {{accessToken}}

About This Endpoint

Modify an existing SIP trunk's configuration parameters without disrupting active calls or requiring trunk recreation. You can update descriptive fields like name and description, adjust capacity settings such as maximum concurrent channels, change operational status to suspend or reactivate trunks, or modify rate limiting thresholds. Configuration changes take effect immediately for new calls while existing calls continue unaffected. This enables dynamic capacity management and operational control without service interruption.

Modifiable Parameters
  • Capacity management: Increase or decrease max_channels to scale trunk capacity
  • Operational control: Change status between active/inactive to suspend/resume service
  • Metadata updates: Modify name, description, and organizational labels
Important Behavior
  • Changes apply immediately to new calls without affecting in-progress calls
  • Cannot modify SIP domain or authentication credentials post-creation
  • Status change to "inactive" prevents new calls but doesn't terminate existing ones
Request Body
{
  "concurrent_calls_limit": 30,
  "cps_limit": 12,
  "ip_whitelist": [
    "198.51.100.10",
    "203.0.113.25"
  ],
  "description": "Updated outbound trunk"
}

Response Example

Success Response (200 OK)
{
  "message": "Trunk updated successfully",
  "trunk": {
    "id": "trunk_7a8b9c0d1e2f3g4h",
    "name": "Updated SIP Trunk Name",
    "description": "Updated description",
    "max_channels": 150,
    "status": "active",
    "updated_at": "2025-10-12T17:00:00.000Z"
  }
}

Delete SIP Trunk

DELETE/api/v1/account/{accountId}/trunks/{trunkId}

Permanently delete a SIP trunk and remove it from the routing infrastructure.

▶HTTP Headers
Host:api.vobiz.ai
Authorization:Bearer {{accessToken}}

Warning: Deleting a trunk will immediately terminate all active calls and remove the trunk from Kamailio. This action cannot be undone.

About This Endpoint

Permanently remove a SIP trunk from your account, immediately terminating all active calls and deregistering the trunk from Kamailio SIP infrastructure. This destructive operation cannot be reversed—the trunk ID, SIP domain, and all associated configuration are permanently deleted. The response includes the count of active calls that were forcibly terminated. Use this endpoint carefully, typically only when decommissioning infrastructure or cleaning up test trunks, as production trunk deletion causes immediate service disruption.

What Gets Deleted
  • Trunk configuration, credentials, and SIP domain are permanently removed
  • All active calls using this trunk are immediately terminated and hung up
  • Kamailio subscriber and routing entries are deleted from SIP infrastructure
Safety Recommendations
  • Check current_channels before deletion to avoid disrupting active calls
  • Consider setting status to "inactive" first to gracefully drain calls
  • Export or backup trunk configuration and statistics before deletion

Response Example

Success Response (200 OK)
{
  "message": "Trunk deleted successfully",
  "deleted_trunk_id": "trunk_7a8b9c0d1e2f3g4h",
  "terminated_calls": 5
}

SIP Domain Format

Every trunk automatically gets a unique SIP domain based on its trunk ID:

<trunkId>.sip.vobiz.ai

Example: If trunk ID is trunk_7a8b9c0d1e2f3g4h, domain is trunk_7a8b9c0d1e2f3g4h.sip.vobiz.ai

SIP URI: sip:+15551234567@trunk_7a8b9c0d1e2f3g4h.sip.vobiz.ai

Port: 5060 (UDP/TCP)

Authentication Types

Password Authentication

SIP digest authentication using username and password. Kamailio validates credentials against the subscriber table.

✓ Most common method

✓ Works from any IP address

✓ Auto-generated credentials

IP-Based Authentication

Whitelist specific IP addresses that can make calls without password. More secure for production deployments.

✓ No password required

✓ Higher security

✓ Requires static IPs

Sub-Accounts
Balance & Billing