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.
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:

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

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.

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

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:

# 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:

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.

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:

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:

{
  "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"]
    }
  }
}

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"
  }
}

DTMF Handling

Configure how DTMF tones (keypad presses) are handled:

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

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:

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: <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:

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 — 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