Skip to main content
Integrate your existing telephony infrastructure with SquawkVoice using standard SIP trunking. This guide covers call routing, security, call transfer, and firewall configuration — with BroadSoft (BroadWorks) as a reference platform.

​
SIP Integration Overview

​
Call Routing & Setup

​
Pointing Your Inbound Number

Configure your telephony platform (e.g. BroadSoft BroadWorks) to route the inbound number to the SquawkVoice SIP domain:

​
Mapping the Call to an AI Agent

Every inbound call must resolve to one AI Agent. There are two ways to do that — pick whichever fits your platform.
Recommended: if your telephony platform forwards the number to SquawkVoice, use number-based routing. It is configured entirely in Studio, needs no custom SIP header, and lets you re-point a number to a different agent without touching your SBC.

​
Option 1: Number-based routing

Add the number to SquawkVoice as a BYO Number and assign it to an agent. SquawkVoice then resolves the agent from the forwarded number on each call.
1

Add the number in Studio

Go to Manage → Phone Numbers, click BYO Number, and add the number in E.164 format — or add a whole consecutive range at once. See Adding a Number You Already Own.
2

Assign it to an AI Agent

Click Assign on the number and pick the agent. Inbound routing updates as soon as the assignment saves, and you can reassign it later without any change on your side.
3

Route the number to the SIP domain

Point the DID at ai-agent-studio.sip.twilio.com as described above, carrying the originally dialed number through to SquawkVoice. Place a test call to confirm it reaches the assigned agent.

​
Option 2: Custom SIP header

Inject a custom SIP header into the INVITE naming the agent directly:
You can find your Agent ID in the SquawkVoice Studio under the agent’s settings page.
Use this when your trunk cannot preserve the forwarding number, or when you want a fixed agent regardless of which number was dialed.

​
Which one wins

X-SIP-AssistantId takes precedence. If the header is present, SquawkVoice routes to that agent and does not look at the number — so remove the header once you switch a number to Option 1, otherwise reassigning the number in Studio will have no effect.
A call that matches neither option is rejected — it is not routed to any agent. Every inbound number needs either an active BYO assignment or the X-SIP-AssistantId header.

​
SBC IP Whitelisting

Before your platform can send inbound calls to SquawkVoice, your SBC (Session Border Controller) IP address must be whitelisted on the SquawkVoice SIP domain. This ensures that only authorised traffic is accepted.
1

Provide Your SBC IP

Share the public IP address of your SBC with the SquawkVoice team. This is the IP from which your SIP INVITE requests will originate.
2

SquawkVoice Whitelists the IP

Our team will add your SBC IP to the access control list (ACL) on the SIP domain. You will be notified once the whitelisting is complete.
3

Verify Connectivity

Place a test call to confirm that your SBC can successfully reach the SquawkVoice SIP domain and that the call is answered by the AI Agent the number is assigned to.
Inbound calls from non-whitelisted IP addresses will be rejected. Ensure your SBC IP is shared with SquawkVoice before going live.

​
Security

SquawkVoice enforces encrypted signaling and media on its SIP domain: Your platform must initiate a secure SIP session using a sips: URI to connect successfully.

​
Call Transfer (SIP REFER)

SquawkVoice uses SIP REFER to transfer calls — for example, when a caller requests escalation to a human agent. Once the REFER is processed, SquawkVoice drops out of the signaling path entirely.

​
Key Requirements

1

Accept SIP REFER without Digest Auth

Your platform must accept SIP REFER from the Twilio SIP domain without requiring Digest authentication. Twilio does not retry a mid-dialog REFER with an Authorization header.
2

Configure the Transfer Destination

In SquawkVoice Studio, navigate to Handoff Configuration → Transfer Rule for your AI Agent. Select a Destination Type (SIP URI or Phone Number) and provide the destination value using one of the three options below.

​
Transfer Destination Options

SquawkVoice supports three ways to define where a call should be transferred:

​
1. Static Value

Enter a fixed SIP URI or phone number directly. Every transfer from this agent will always go to the same destination.
Use a static destination when all transfers should route to a single, known endpoint — for example, a contact centre SBC.

​
2. Variable-Based Destination

Use a {{variable}} to dynamically resolve the transfer destination at runtime. The variable value can be populated via a Pre-Call Action (e.g. a directory lookup) or a During-Call Action (e.g. an API call that returns the right department SIP URI).
This is useful when different callers need to be routed to different destinations based on their account, region, or issue type.

​
3. AI-Resolved Destination

Use the special variable {{interaction.TRANSFER_DESTINATION}} to let the AI Agent automatically determine the transfer destination based on the context of the conversation and the outputs of During-Call Actions.
When this variable is used, the AI is given the destination type context (SIP URI or Phone Number) and will resolve the appropriate value dynamically — for example, picking the right department number based on what the caller asked for.
The AI-resolved option is ideal when your agent handles multiple transfer scenarios and you want the AI to intelligently route based on the conversation flow rather than hardcoding every possible destination.

​
AI Call Context in SIP Headers

When transferring to a SIP destination, SquawkVoice can pass the AI conversation’s outcome to the receiving system inline as SIP headers — no screen-pop lookup required. Enable Context in SIP Headers in the agent’s Handoff Configuration (Transfer Rule). When enabled, the outbound REFER/INVITE carries: Behavior notes:
  • Headers are added on SIP-destination transfers only (both SIP REFER and WebRTC SIP dial paths); phone-number transfers are unaffected.
  • Twilio limits SIP headers to 1,024 characters — if the budget is exceeded, only X-SV-Summary is truncated; the disposition is always sent intact.
  • Only the brief summary is sent — never the full transcript.
  • Header injection is non-blocking: if the summary is not yet available at transfer time, the transfer proceeds without the context headers.
  • Works together with the existing Screen Pop option — when both are enabled, the screen-pop headers (User-to-User, X-SquawkVoice-Session) and the context headers are sent on the same transfer.

​
Firewall Rules

To allow SIP signaling and media traffic from SquawkVoice, add the following rules to your firewall. The IP ranges below correspond to the Twilio North America — Virginia gateway region.

​
SIP Signaling

​
RTP Media

These IP ranges are specific to Twilio’s North America Virginia region. If your deployment uses a different region, consult the Twilio IP address documentation for the correct ranges.

​
Example: BroadSoft BroadWorks Configuration

Below is a summary of a complete SIP integration between BroadSoft BroadWorks and SquawkVoice:

​
Need Help?

If you have questions about SIP integration or need assistance configuring your telephony platform, reach out to our team: