SIP trunking deployment

Overview

Iqra AI supports SIP trunking for enterprise-grade telephony deployment. Connect your existing phone infrastructure or use cloud telephony providers to route calls through Iqra AI’s conversational agents. The platform implements a two-tier SIP architecture:

Proxy layer - Load balances incoming SIP INVITE requests across backend servers
Backend layer - Handles media processing and AI conversation orchestration

Supported providers

Iqra AI integrates with multiple telephony providers:

Twilio
Telnyx
Vonage
Direct SIP

Twilio configuration

Twilio uses TwiML and WebSocket streaming for real-time audio.Authentication: Basic auth with Account SID and Auth TokenKey features:

Voice URL webhook configuration
Status callback for call lifecycle events
Media streaming via WebSocket
Support for both inbound and outbound calls

Implementation: See IqraInfrastructure/Managers/Telephony/TwilioManager.cs:136

// Outbound call with WebSocket streaming
var voiceResponse = new VoiceResponse();
var connect = new Connect();
var stream = new Stream(url: websocketUrl);
connect.Append(stream);
voiceResponse.Append(connect);

Twilio requires VoiceReceiveMode set to “voice” for full-duplex audio streaming.

Telnyx configuration

Telnyx provides native SIP and WebRTC connectivity with advanced call control.Authentication: Bearer token (API key)Key features:

Bidirectional RTP streaming
DTMF tone support
WebRTC and SIP endpoints
Connection-based routing

Audio configuration:

Codec: PCMA (G.711 A-law)
Sample rate: 8000 Hz
Mode: Bidirectional RTP
Tracks: Both inbound and outbound

Implementation: See IqraInfrastructure/Managers/Telephony/TelnyxManager.cs:40

var dialRequest = new {
    StreamUrl = streamUrl,
    StreamTrack = "both_tracks",
    StreamCodex = "PCMA",
    StreamBidirectionalMode = "rtp",
    StreamBidirectionalSamplingRate = 8000
};

Vonage (Nexmo) configuration

Vonage uses dual authentication and NCCO for call control.Authentication:

API calls: JWT Bearer token
Number management: Basic auth (API Key + Secret)

Key features:

NCCO (Nexmo Call Control Objects) for call flow
WebSocket endpoint connections
L16 audio format support (16-bit linear PCM)
Event URL callbacks

Implementation: See IqraInfrastructure/Managers/Telephony/VonageManager.cs:55

var ncco = new[] {
    new {
        Action = "connect",
        Endpoint = new[] {
            new {
                Type = "websocket",
                Uri = websocketUrl,
                ContentType = "audio/l16;rate=8000"
            }
        }
    }
};

Vonage requires separate HTTP clients for API operations (api.nexmo.com) vs number management (rest.nexmo.com).

Direct SIP trunk configuration

Connect your own SIP infrastructure directly to Iqra AI.Supported protocols:

UDP (primary)
TCP (fallback)
TLS (for secure connections)

Configuration options:

E.164 number format support
Custom SIP username/password override
IP-based access control lists (ACL)

Implementation: See IqraInfrastructure/Managers/SIP/SipProxyService.cs:63

Direct SIP numbers support IP whitelisting via the AllowedSourceIps configuration.

Architecture

SIP proxy service

The proxy service handles initial call routing and load balancing:

Receive SIP INVITE

Proxy listens on configurable port (UDP/TCP) for incoming INVITE requests.

SIPTransport.AddSIPChannel(new SIPUDPChannel(port))
SIPTransport.AddSIPChannel(new SIPTCPChannel(port))

Validate business and number

Extract business ID and phone ID from SIP URI parameters:

sip:[email protected]?X-Business-Id=123&X-Phone-Id=abc

Validates:

Business exists and is active
Number is configured for the business
Number provider matches (SIP, Twilio, etc.)
Route ID is configured

Check plan limits

Validates call concurrency limits based on subscription tier before accepting the call.

Apply ACL rules

For SIP numbers with IP restrictions, validates source IP against AllowedSourceIps list.

Select backend server

Chooses optimal backend server based on:

Region affinity
Current capacity
Admin bypass rules

Redirect to backend

Returns 302 Moved Temporarily with Contact header pointing to selected backend:

Contact: <sip:[email protected]:5060?X-CallQueue-Id=queue123>

Source: IqraInfrastructure/Managers/SIP/SipProxyService.cs:134

SIP backend listener

The backend service handles actual media processing:

Accept redirected call

Backend listener receives the redirected INVITE with call queue ID parameter.

Validate queue entry

Retrieves call queue entry and verifies:

Queue exists and is in ProcessedProxy state
Region and server ID match
Not already processing

Create conversation session

Hands off to BackendCallProcessorManager to:

Initialize conversation orchestrator
Create AI agent
Setup telephony client
Configure audio pipeline

Answer call

Sends SIP 200 OK response with SDP to establish media session.

Source: IqraInfrastructure/Managers/SIP/SipBackendListenerService.cs:99

Deployment patterns

Provider-based routing

Route calls through cloud telephony providers: Use cases:

Quick deployment without infrastructure
Global phone number provisioning
Built-in redundancy and failover

Direct SIP trunking

Connect enterprise PBX directly to Iqra AI: Use cases:

Existing telephony infrastructure
Regulatory compliance requirements
Cost optimization for high call volumes

Hybrid deployment

Combine provider and direct SIP:

Use Twilio for US/Canada numbers
Use direct SIP for internal extensions
Use Telnyx for international markets

Configuration

Number registration

{
  "provider": "SIP",
  "number": "+15551234567",
  "routeId": "route-abc123",
  "regionId": "us-east-1",
  "isE164Number": true,
  "allowedSourceIps": [
    "203.0.113.10",
    "203.0.113.11"
  ]
}

Provider credentials

Store provider credentials securely:

Twilio
Telnyx
Vonage

{
  "accountSid": "ACxxxxxxxxxxxxx",
  "authToken": "your_auth_token",
  "voiceUrl": "https://your-backend/webhooks/twilio/voice",
  "statusCallbackUrl": "https://your-backend/webhooks/twilio/status"
}

{
  "apiKey": "KEYxxxxxxxxxxxxx",
  "connectionId": "conn_xxxxxxxxxxxxx",
  "webhookUrl": "https://your-backend/webhooks/telnyx"
}

{
  "apiKey": "abcd1234",
  "apiSecret": "your_api_secret",
  "applicationId": "app-xxxxxxxxxxxxx",
  "privateKey": "-----BEGIN PRIVATE KEY-----\n..."
}

Audio codecs

Supported audio formats for SIP:

Codec	Sample Rate	Description
PCMU (μ-law)	8000 Hz	G.711 mu-law, common in North America
PCMA (A-law)	8000 Hz	G.711 A-law, common in Europe
G.722	16000 Hz	Wideband audio
OPUS	48000 Hz	Modern codec with WebRTC

Call lifecycle

Inbound call flow

Call initiated

Customer calls your phone number. Provider sends SIP INVITE or webhook to Iqra AI.

Proxy routing

SIP proxy validates and routes to available backend server.

Session creation

Backend creates conversation session with AI agent and telephony client.

Call answered

SIP 200 OK sent, media session established, AI greeting plays.

Conversation

Real-time bidirectional audio between customer and AI agent.

Call termination

Either party hangs up. Session cleanup, billing recorded, webhooks fired.

Outbound call flow

API trigger

Application calls Iqra AI API to initiate outbound call.

Provider API call

Backend calls Twilio/Telnyx/Vonage API to dial customer number.

Call connects

Provider establishes call, sends audio stream to Iqra AI backend.

AI conversation

Same bidirectional conversation flow as inbound calls.

Monitoring and troubleshooting

Call queue tracking

Each call creates an entry in the InboundCallQueue collection:

{
  "id": "queue-123",
  "status": "ProcessedProxy",
  "providerCallId": "call-abc",
  "businessId": 12345,
  "routeNumberId": "num-xyz",
  "processingProxyServerId": "proxy-1",
  "processingBackendServerId": "backend-2",
  "enqueuedAt": "2024-01-15T10:30:00Z",
  "logs": [
    {"type": "Info", "message": "Call routed to backend-2"}
  ]
}

Common issues

SIP 503 Service Unavailable: No backend servers available in the region. Check server health and capacity limits.

SIP 403 Forbidden: Source IP not in ACL. Add caller IP to AllowedSourceIps for the number.

SIP 404 Not Found: Number or route not configured. Verify number registration and route ID.

Status codes

SIP Code	Description	Common Cause
100 Trying	Processing request	Normal
200 OK	Call established	Success
302 Moved Temporarily	Redirecting to backend	Normal proxy operation
403 Forbidden	ACL rejection	Source IP not whitelisted
404 Not Found	Number/route missing	Configuration error
503 Service Unavailable	No capacity	All backends busy

Best practices

Use regional backends: Deploy backend servers in the same region as your customers to minimize latency.

Configure failover: Set up multiple providers for redundancy. If Twilio fails, route to Telnyx.

Monitor concurrency: Track CallConcurrency metrics to avoid hitting subscription limits during peak hours.

Secure SIP trunks: Always use IP whitelisting for direct SIP connections. Consider TLS for encryption.

Next steps

WebRTC integration - Add browser-based voice calls
WebSocket integration - Custom audio streaming
Voice configuration - Configure AI voice settings

Getting Started

Core Concepts

Building Agents

Integrations

Knowledge Base & RAG

Deployment

Channels

SIP trunking deployment

Overview

Supported providers

Twilio configuration

Telnyx configuration

Vonage (Nexmo) configuration

Direct SIP trunk configuration

Architecture

SIP proxy service

SIP backend listener

Deployment patterns

Provider-based routing

Direct SIP trunking

Hybrid deployment

Configuration

Number registration

Provider credentials

Audio codecs

Call lifecycle

Inbound call flow

Outbound call flow

Monitoring and troubleshooting

Call queue tracking

Common issues

Status codes

Best practices

Next steps

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Building Agents

Integrations

Knowledge Base & RAG

Deployment

Channels

​Overview

​Supported providers

​Twilio configuration

​Telnyx configuration

​Vonage (Nexmo) configuration

​Direct SIP trunk configuration

​Architecture

​SIP proxy service

​SIP backend listener

​Deployment patterns

​Provider-based routing

​Direct SIP trunking

​Hybrid deployment

​Configuration

​Number registration

​Provider credentials

​Audio codecs

​Call lifecycle

​Inbound call flow

​Outbound call flow

​Monitoring and troubleshooting

​Call queue tracking

​Common issues

​Status codes

​Best practices

​Next steps

Build docs developers (and LLMs) love

Overview

Supported providers

Twilio configuration

Telnyx configuration

Vonage (Nexmo) configuration

Direct SIP trunk configuration

Architecture

SIP proxy service

SIP backend listener

Deployment patterns

Provider-based routing

Direct SIP trunking

Hybrid deployment

Configuration

Number registration

Provider credentials

Audio codecs

Call lifecycle

Inbound call flow

Outbound call flow

Monitoring and troubleshooting

Call queue tracking

Common issues

Status codes

Best practices

Next steps