> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# SIP Integration
> Connect your SIP trunks from Twilio and Vobiz to thinnestAI for enterprise telephony integration with your voice agents.
# 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
1. Log in to your [Twilio Console](https://console.twilio.com).
2. Navigate to **Elastic SIP Trunking → Trunks**.
3. Click **Create new SIP Trunk**.
4. Name it (e.g., "thinnestAI Voice Agents").
### Step 2: Configure the Origination URI
The origination URI tells Twilio where to send incoming calls.
1. In your SIP Trunk settings, go to **Origination**.
2. Add a new Origination URI:
```bash theme={null}
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):
```bash theme={null}
sip:voice.thinnest.ai:5061;transport=tls
```
### Step 3: Configure Termination
Termination handles outbound calls from thinnestAI through your Twilio trunk.
1. Go to **Termination** in your SIP Trunk settings.
2. Set the **Termination SIP URI**:
```bash theme={null}
your-trunk-name.pstn.twilio.com
```
3. Add **Credentials** for authentication:
* Create a Credential List in Twilio
* Add a username and password
* Note these credentials for the thinnestAI configuration
4. Add the thinnestAI IP addresses to your **IP Access Control List**:
```bash theme={null}
# 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:
1. Go to **Settings → SIP Integration → Add Provider**.
2. Select **Twilio SIP**.
3. Enter your configuration:
```bash theme={null}
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
```
4. Click **Test Connection** to verify.
5. Click **Save**.
### Step 5: Assign a Phone Number
1. In Twilio, go to **Phone Numbers → Active Numbers**.
2. Select the number you want to route to thinnestAI.
3. Under **Voice Configuration**, set:
* **Configure with**: SIP Trunk
* **SIP Trunk**: Select the trunk you created
4. In thinnestAI, go to **Settings → Phone Numbers → Add Number**.
5. Enter the phone number and select the SIP trunk you configured.
6. 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
1. Go to **Settings → SIP Integration → Add Provider**.
2. Select **Vobiz SIP**.
3. Enter your credentials:
```bash theme={null}
VOBIZ_SIP_SERVER=sip.vobiz.com
VOBIZ_SIP_USERNAME=your_username
VOBIZ_SIP_PASSWORD=your_password
VOBIZ_SIP_PORT=5060
VOBIZ_SIP_TRANSPORT=udp
```
4. Click **Test Connection**.
5. Click **Save**.
### Step 3: Configure Inbound Routing
Set up how inbound calls from your Vobiz numbers reach your agents:
```json theme={null}
{
"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:
```json theme={null}
{
"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
(`sip:USER:PASS@HOST` 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:
1. **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.
2. **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 `…` 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.
```json theme={null}
{
"sip_auth": {
"method": "ip",
"allowed_ips": [
"203.0.113.10/32",
"203.0.113.11/32"
]
}
}
```
**Digest authentication:**
Standard SIP username/password authentication.
```json theme={null}
{
"sip_auth": {
"method": "digest",
"username": "your_sip_username",
"password": "your_sip_password",
"realm": "thinnest.ai"
}
}
```
### TLS Configuration
For encrypted SIP signaling:
```json theme={null}
{
"sip_transport": {
"protocol": "tls",
"port": 5061,
"verify_certificate": true
}
}
```
For encrypted media (SRTP):
```json theme={null}
{
"sip_media": {
"srtp": true,
"srtp_mode": "require"
}
}
```
## Inbound Routing via SIP
### DID-Based Routing
Route calls based on the dialed number (DID):
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"sip_session": {
"session_timer": 1800,
"min_session_timer": 90,
"session_refresher": "uac"
}
}
```
## Multi-Provider Setup
Use multiple SIP providers for redundancy:
```json theme={null}
{
"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:**
1. Verify the origination URI is correct: `sip:voice.thinnest.ai:5060`
2. Check that your SIP trunk is enabled and active
3. Confirm your DID is assigned to an agent in thinnestAI
4. Check firewall rules — SIP uses UDP/TCP port 5060 and TLS port 5061
5. Verify media ports are open (UDP 10000-60000 for RTP)
#### One-Way Audio
**Symptom:** Only one side can hear the other.
**Checklist:**
1. Check NAT settings on your firewall — SIP requires symmetric NAT or STUN
2. Verify RTP ports are open in both directions
3. Check codec compatibility between your provider and thinnestAI
4. Ensure SRTP settings match on both sides
#### Registration Failures
**Symptom:** SIP registration fails with 401 or 403 errors.
**Checklist:**
1. Verify SIP username and password
2. Check that the realm matches your provider's expected value
3. Confirm your IP is in the provider's allow list
4. Check for clock skew — SIP digest auth is time-sensitive
#### Poor Audio Quality
**Symptom:** Choppy, delayed, or garbled audio.
**Checklist:**
1. Check network bandwidth — each call needs \~100 kbps
2. Look for packet loss (should be below 1%)
3. Check jitter (should be below 30ms)
4. Consider switching to a lower-bandwidth codec (G.729)
5. Use QoS/DSCP marking for SIP traffic on your network
### SIP Debugging
Enable SIP debug logging in the dashboard:
1. Go to **Settings → SIP Integration → Diagnostics**.
2. Toggle **SIP Debug Logging** to on.
3. Make a test call.
4. 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: ;tag=abc123
To:
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:
1. Capture a SIP trace (enable debug logging, make a test call).
2. Note the Call-ID from the SIP headers.
3. Contact thinnestAI support with the trace and Call-ID.
4. Our team can correlate the call on our side and identify the issue.
## Next Steps
* [Inbound Calls](/docs/voice/inbound-calls) — Set up agents for your SIP-connected numbers
* [Outbound Calls](/docs/voice/outbound-calls) — Make outbound calls through your SIP trunks
* [Voice Configuration](/docs/voice/voice-configuration) — Configure voice settings for SIP calls