SIP Integration

SIP (Session Initiation Protocol) trunking connects your existing phone infrastructure to thinnestAI. If you already have SIP trunks, PBX systems, or contact center platforms, you can route calls through them to your voice agents without changing your telephony setup.

What is SIP Trunking?

SIP trunking replaces traditional phone lines with internet-based connections. Instead of physical phone lines, your calls travel as data over the internet using the SIP protocol.

Your PBX / Contact Center
        ↓ (SIP)
  SIP Trunk Provider (Twilio / Vobiz)
        ↓ (SIP)
  thinnestAI Voice Engine
        ↓
  AI Agent handles the call

Benefits of SIP integration:

Use your existing numbers — No need to port numbers or change providers
Keep your infrastructure — Works alongside your current PBX, IVR, or contact center
Flexible routing — Route some calls to AI agents and others to human agents
Lower cost — Leverage existing SIP contracts and rates
Redundancy — Failover between providers

Setting Up SIP Trunks with Twilio

Twilio Elastic SIP Trunking is the most common way to connect SIP to thinnestAI.

Step 1: Create a Twilio SIP Trunk

Log in to your Twilio Console.
Navigate to Elastic SIP Trunking → Trunks.
Click Create new SIP Trunk.
Name it (e.g., “thinnestAI Voice Agents”).

Step 2: Configure the Origination URI

The origination URI tells Twilio where to send incoming calls.

In your SIP Trunk settings, go to Origination.
Add a new Origination URI:

sip:voice.thinnest.ai:5060;transport=udp

Setting	Value
Origination URI	`sip:voice.thinnest.ai:5060;transport=udp`
Priority	10 (primary)
Weight	100
Enabled	Yes

For TLS (recommended for production):

sip:voice.thinnest.ai:5061;transport=tls

Step 3: Configure Termination

Termination handles outbound calls from thinnestAI through your Twilio trunk.

Go to Termination in your SIP Trunk settings.
Set the Termination SIP URI:

your-trunk-name.pstn.twilio.com

Add Credentials for authentication:
- Create a Credential List in Twilio
- Add a username and password
- Note these credentials for the thinnestAI configuration
Add the thinnestAI IP addresses to your IP Access Control List:

# thinnestAI SIP endpoints (contact support for current IPs)
203.0.113.10/32
203.0.113.11/32

Step 4: Configure thinnestAI

In the thinnestAI dashboard:

Go to Settings → SIP Integration → Add Provider.
Select Twilio SIP.
Enter your configuration:

TWILIO_SIP_TRUNK_SID=TKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_SIP_DOMAIN=your-trunk-name.pstn.twilio.com
TWILIO_SIP_USERNAME=your_sip_username
TWILIO_SIP_PASSWORD=your_sip_password

Click Test Connection to verify.
Click Save.

Step 5: Assign a Phone Number

In Twilio, go to Phone Numbers → Active Numbers.
Select the number you want to route to thinnestAI.
Under Voice Configuration, set:
- Configure with: SIP Trunk
- SIP Trunk: Select the trunk you created
In thinnestAI, go to Settings → Phone Numbers → Add Number.
Enter the phone number and select the SIP trunk you configured.
Assign the number to your voice agent.

Per-phone Twilio webhooks

When you import a Twilio number via BYOK (POST /voice/twilio/byok/import), thinnestAI provisions two per-phone webhook URLs and returns them in the import response:

Voice URL  :  https://api.thinnest.ai/twilio/incoming/{phone_id}
Status URL :  https://api.thinnest.ai/twilio/status/{phone_id}

Both endpoints verify the X-Twilio-Signature header against your account’s auth token, generate the TwiML to dial the LiveKit SIP trunk on the answer URL, and update voice_sessions.telephony_status on the status URL. Configure the URLs in the Twilio console under your phone number’s voice settings.

Vobiz SIP Integration

Vobiz provides SIP trunking optimized for AI voice applications.

Step 1: Get Vobiz Credentials

Contact Vobiz to set up your SIP trunk. You will receive:

SIP server address
SIP username
SIP password
Allocated phone numbers (DIDs)

Step 2: Configure thinnestAI

Go to Settings → SIP Integration → Add Provider.
Select Vobiz SIP.
Enter your credentials:

VOBIZ_SIP_SERVER=sip.vobiz.com
VOBIZ_SIP_USERNAME=your_username
VOBIZ_SIP_PASSWORD=your_password
VOBIZ_SIP_PORT=5060
VOBIZ_SIP_TRANSPORT=udp

Click Test Connection.
Click Save.

Step 3: Configure Inbound Routing

Set up how inbound calls from your Vobiz numbers reach your agents:

{
  "sip_config": {
    "provider": "vobiz",
    "inbound_routing": [
      {
        "did": "+14155551234",
        "agent_id": "agent_support",
        "description": "Main support line"
      },
      {
        "did": "+14155555678",
        "agent_id": "agent_sales",
        "description": "Sales line"
      },
      {
        "did_pattern": "+1415555*",
        "agent_id": "agent_general",
        "description": "All other numbers"
      }
    ]
  }
}

Step 4: Configure Outbound Calling

To make outbound calls through your Vobiz trunk:

{
  "sip_config": {
    "provider": "vobiz",
    "outbound": {
      "enabled": true,
      "caller_id": "+14155551234",
      "codec_preference": ["PCMU", "PCMA", "G729"]
    }
  }
}

Plivo SIP Integration

Plivo numbers carry their own webhook signature scheme (X-Plivo-Signature-V3, HMAC-SHA256 over url + nonce + body). The signature is verified using the same auth token you provided when importing the number — no additional credential needed. After POST /voice/plivo/byok/import returns, point Plivo’s Application URLs at:

Answer URL :  https://api.thinnest.ai/plivo/incoming/{phone_id}
Hangup URL :  https://api.thinnest.ai/plivo/status/{phone_id}

Both endpoints fail closed without X-Plivo-Signature-V3 + X-Plivo-Signature-V3-Nonce headers, so requests from anyone other than Plivo are rejected. The answer URL returns PlivoXML that dials the LiveKit SIP trunk (<Dial><User>sip:USER:PASS@HOST</User></Dial> per RFC 3261). The hangup URL updates voice_sessions.telephony_status with the final state.

Exotel SIP Integration

Exotel doesn’t sign webhooks, so the per-phone endpoints (/exotel/incoming/{phone_id} and /exotel/status/{phone_id}) use two layers of protection:

IP allowlist — EXOTEL_ALLOWED_IPS env (comma-separated). Empty in production = endpoint refuses all traffic. The default ships with the current Exotel AP-South-1 + US-West-2 callback IPs baked in; override the env if Exotel rotates.
Per-phone token — append ?token=… to the webhook URL you configure in the Exotel ExoML / passthrough flow. Store the same token in phone_numbers.config.exotel_webhook_token. Tokens are compared with hmac.compare_digest to avoid timing attacks.

Configure the URLs in the Exotel passthrough flow:

Answer URL :  https://api.thinnest.ai/exotel/incoming/{phone_id}?token={your_token}
Status URL :  https://api.thinnest.ai/exotel/status/{phone_id}?token={your_token}

The answer URL returns ExoML <Dial><Sip>…</Sip></Dial> to bridge the call into the LiveKit SIP trunk. The status URL updates voice_sessions.telephony_status.

Configuring SIP Credentials

Authentication Methods

thinnestAI supports two SIP authentication methods: IP-based authentication: Allow traffic from specific IP addresses without username/password.

{
  "sip_auth": {
    "method": "ip",
    "allowed_ips": [
      "203.0.113.10/32",
      "203.0.113.11/32"
    ]
  }
}

Digest authentication: Standard SIP username/password authentication.

{
  "sip_auth": {
    "method": "digest",
    "username": "your_sip_username",
    "password": "your_sip_password",
    "realm": "thinnest.ai"
  }
}

TLS Configuration

For encrypted SIP signaling:

{
  "sip_transport": {
    "protocol": "tls",
    "port": 5061,
    "verify_certificate": true
  }
}

For encrypted media (SRTP):

{
  "sip_media": {
    "srtp": true,
    "srtp_mode": "require"
  }
}

Inbound Routing via SIP

DID-Based Routing

Route calls based on the dialed number (DID):

{
  "inbound_routing": [
    {
      "did": "+14155551234",
      "agent_id": "agent_support"
    },
    {
      "did": "+14155555678",
      "agent_id": "agent_sales"
    }
  ]
}

Header-Based Routing

Route based on SIP headers for advanced use cases:

{
  "inbound_routing": [
    {
      "sip_header": "X-Department",
      "value": "billing",
      "agent_id": "agent_billing"
    },
    {
      "sip_header": "X-Priority",
      "value": "high",
      "agent_id": "agent_priority"
    }
  ]
}

Caller ID Routing

Route based on who is calling:

{
  "inbound_routing": [
    {
      "caller_pattern": "+44*",
      "agent_id": "agent_uk"
    },
    {
      "caller_pattern": "+1*",
      "agent_id": "agent_us"
    }
  ]
}

Failover Routing

Configure what happens when an agent is unavailable:

{
  "inbound_routing": [
    {
      "did": "+14155551234",
      "agent_id": "agent_primary",
      "failover": {
        "agent_id": "agent_backup",
        "timeout_seconds": 10
      },
      "final_failover": {
        "action": "forward",
        "number": "+18005559999"
      }
    }
  ]
}

Advanced SIP Configuration

Codec Selection

Configure audio codec preferences:

{
  "sip_codecs": {
    "preferred": ["PCMU", "PCMA"],
    "allowed": ["PCMU", "PCMA", "G729", "opus"],
    "dtmf_method": "rfc2833"
  }
}

Codec	Quality	Bandwidth	Notes
PCMU (G.711u)	High	64 kbps	Standard, best compatibility
PCMA (G.711a)	High	64 kbps	European standard
G.729	Good	8 kbps	Low bandwidth, requires license
Opus	Excellent	Variable	Best quality, WebRTC native

DTMF Handling

Configure how DTMF tones (keypad presses) are handled:

{
  "dtmf_config": {
    "method": "rfc2833",
    "fallback": "inband",
    "pass_to_agent": true
  }
}

Method	Description
`rfc2833`	Out-of-band, most reliable (recommended)
`sip_info`	SIP INFO messages
`inband`	In-band audio detection

Your agent can interpret DTMF input if needed (e.g., the caller presses “1” to confirm).

Session Timers

Prevent stuck calls with SIP session timers:

{
  "sip_session": {
    "session_timer": 1800,
    "min_session_timer": 90,
    "session_refresher": "uac"
  }
}

Multi-Provider Setup

Use multiple SIP providers for redundancy:

{
  "sip_providers": [
    {
      "name": "Twilio Primary",
      "provider": "twilio",
      "priority": 1,
      "config": {
        "trunk_sid": "TKxxxxxxxx",
        "domain": "trunk1.pstn.twilio.com"
      }
    },
    {
      "name": "Vobiz Backup",
      "provider": "vobiz",
      "priority": 2,
      "config": {
        "server": "sip.vobiz.com",
        "username": "backup_user"
      }
    }
  ],
  "failover": {
    "enabled": true,
    "failover_on": ["timeout", "503", "480"],
    "timeout_seconds": 5
  }
}

If the primary provider fails, calls automatically route through the backup.

Troubleshooting SIP Connections

Common Issues

Calls Not Reaching thinnestAI

Symptom: Inbound calls ring but the agent never picks up. Checklist:

Verify the origination URI is correct: sip:voice.thinnest.ai:5060
Check that your SIP trunk is enabled and active
Confirm your DID is assigned to an agent in thinnestAI
Check firewall rules — SIP uses UDP/TCP port 5060 and TLS port 5061
Verify media ports are open (UDP 10000-60000 for RTP)

One-Way Audio

Symptom: Only one side can hear the other. Checklist:

Check NAT settings on your firewall — SIP requires symmetric NAT or STUN
Verify RTP ports are open in both directions
Check codec compatibility between your provider and thinnestAI
Ensure SRTP settings match on both sides

Registration Failures

Symptom: SIP registration fails with 401 or 403 errors. Checklist:

Verify SIP username and password
Check that the realm matches your provider’s expected value
Confirm your IP is in the provider’s allow list
Check for clock skew — SIP digest auth is time-sensitive

Poor Audio Quality

Symptom: Choppy, delayed, or garbled audio. Checklist:

Check network bandwidth — each call needs ~100 kbps
Look for packet loss (should be below 1%)
Check jitter (should be below 30ms)
Consider switching to a lower-bandwidth codec (G.729)
Use QoS/DSCP marking for SIP traffic on your network

SIP Debugging

Enable SIP debug logging in the dashboard:

Go to Settings → SIP Integration → Diagnostics.
Toggle SIP Debug Logging to on.
Make a test call.
Review the SIP message trace.

The trace shows the full SIP dialog:

INVITE sip:agent@voice.thinnest.ai SIP/2.0
Via: SIP/2.0/UDP 203.0.113.10:5060
From: <sip:+14155551234@trunk.twilio.com>;tag=abc123
To: <sip:agent@voice.thinnest.ai>
Call-ID: xyz789@203.0.113.10
CSeq: 1 INVITE
Content-Type: application/sdp
...

SIP/2.0 200 OK
...

Use this to identify where the connection is failing.

Getting Help

If you cannot resolve a SIP issue:

Capture a SIP trace (enable debug logging, make a test call).
Note the Call-ID from the SIP headers.
Contact thinnestAI support with the trace and Call-ID.
Our team can correlate the call on our side and identify the issue.

Next Steps

Inbound Calls — Set up agents for your SIP-connected numbers
Outbound Calls — Make outbound calls through your SIP trunks
Voice Configuration — Configure voice settings for SIP calls

​SIP Integration

​What is SIP Trunking?

​Setting Up SIP Trunks with Twilio

​Step 1: Create a Twilio SIP Trunk

​Step 2: Configure the Origination URI

​Step 3: Configure Termination

​Step 4: Configure thinnestAI

​Step 5: Assign a Phone Number

​Per-phone Twilio webhooks

​Vobiz SIP Integration

​Step 1: Get Vobiz Credentials

​Step 2: Configure thinnestAI

​Step 3: Configure Inbound Routing

​Step 4: Configure Outbound Calling

​Plivo SIP Integration

​Exotel SIP Integration

​Configuring SIP Credentials

​Authentication Methods

​TLS Configuration

​Inbound Routing via SIP

​DID-Based Routing

​Header-Based Routing

​Caller ID Routing

​Failover Routing

​Advanced SIP Configuration

​Codec Selection

​DTMF Handling

​Session Timers

​Multi-Provider Setup

​Troubleshooting SIP Connections

​Common Issues

​Calls Not Reaching thinnestAI

​One-Way Audio

​Registration Failures

​Poor Audio Quality

​SIP Debugging

​Getting Help

​Next Steps