{{interaction.DNIS}} is the number your contact was dialled on, in +E.164 form (see Adding a Number You Already Own).
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. You set the agent mapping up in Studio, it needs no custom SIP header, and it lets you re-point a number to a different agent without touching your SBC. It needs BYO Number to be enabled for your account — see Option 1. Until it is, use Option 2.
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.BYO Number is off by default. If you do not see the button, ask your provider to enable it for your account. Until it is on, map calls to an agent with Option 2.
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. Phone Numbers isn’t in the default sidebar: add it with Customize sidebar, or press Cmd/Ctrl+K and search for it. See Navigating Studio.
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 theINVITE naming the agent directly:
To get an agent’s ID, open the agent from Build → AI Agents and select Copy ID in the header at the top of the page, just under the agent’s name. Studio confirms with Assistant ID copied. In a narrow window the button shows only a copy icon — hover it to see Copy agent ID. The ID is also the part of the page address right after
/build/. See The Agent Header.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.
How an Inbound Call Finds Its Agent
Unless the call carries anX-SIP-AssistantId header (see Which one wins), the answering agent is resolved from the number that was dialed, using that number’s current assignment in SquawkVoice. Reassigning a number therefore takes effect without any change on your side, and several numbers can point at the same agent. A number with no active assignment fails to route.
SquawkVoice matches on the digits of the dialed number, so your trunk can present it as a phone number such as +14155551234 or as a SIP address such as sip:+14155551234@sbc.example.com. Your Pre-conversation Actions receive the caller’s and dialed numbers as {{interaction.ANI}} and {{interaction.DNIS}} exactly as your trunk presents them, so on a SIP trunk either may be a SIP address too. See Call Lifecycle Hooks.
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.
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)
When a caller asks to be transferred — for example, to a human agent — SquawkVoice follows the agent’s Transfer Rule. How the call is transferred depends on its Destination Type:Key Requirements
1
Accept SIP REFER without Digest Auth (SIP URI destinations)
If you transfer to a SIP URI, 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. This doesn’t apply to Phone Number destinations.2
Configure the Transfer Destination
In SquawkVoice Studio, go to Build → AI Agents, open your AI Agent, then open Handoff. On the Voice tab, find Transfer Rule. Select a Destination Type (SIP URI or Phone Number — Phone Number is the default) and provide the destination value using one of the three options below.
If the Handoff card is greyed out, Transfer is switched off for the agent — see Toggle Transfer. If Transfer Rule isn’t on the Voice tab, contact your provider.
A browser test call started with Talk in Studio isn’t a SIP call, so its transfers don’t use
REFER: SquawkVoice dials the SIP address as a new call. If the agent has a usable number bought in the Studio, that call shows the earliest-assigned one as its caller ID. A transfer to a SIP URI still carries the Screen Pop token and the Inline SIP context headers when you have turned them on, so you can try the receiving system without a real phone call. A Talk call has no real caller number, so the caller number on the Screen Pop page may look odd. See Testing Transfers.Transfer Rule Settings
These settings sit on the Voice tab of Handoff, under Transfer settings. Which ones you see depends on the Destination Type. On an agent that has been published, a change to them reaches real calls, SIP calls included, at your next Publish, while a Talk test call uses what you’ve saved. See What Waits for Publish.Changing the Destination Type switches off the options that belong to the other type. Moving to Phone Number turns off Screen Pop and Inline SIP context headers; moving to SIP URI turns off Enable Handoff Transcript and Enable Handoff Recording. Turn them back on if you switch back.
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-conversation Action (e.g. a directory lookup) or an In-conversation Action (e.g. an API call that returns the right department SIP URI).
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 In-conversation Actions.
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. Turn on Inline SIP context headers in the agent’s Handoff → Voice → Transfer Rule. The switch appears only when Destination Type is SIP URI, next to Screen Pop. When enabled, the outboundREFER/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-Summaryis 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 Screen Pop — when both are enabled, the screen-pop headers (
User-to-User,X-SquawkVoice-Session) and the context headers are sent on the same transfer. The screen-pop headers use part of the same 1,024-character limit, so with both on,X-SV-Summaryis shortened sooner.
Screen Pop
Screen Pop puts what the AI agent already learned in front of the person who takes the transfer, in a web page, so the caller doesn’t have to start again. It works with SIP URI destinations only. To use it, open the agent’s Handoff → Voice → Transfer Rule, set Destination Type to SIP URI, and turn on Screen Pop. It is off by default.Turning on Screen Pop doesn’t open anything by itself. SquawkVoice sends a short-lived token with the transfer, and your telephony platform or agent desktop has to use it to open the page for the receiving agent.
What is sent with the transfer
The token travels in two SIP headers on the transfer:
Only the token is sent, never a link and never the conversation itself.
Opening the page
Open this address for the receiving agent, with either header value as thetoken:
;encoding=hex ending can stay on. Don’t build a link to the page itself, because the address above hands the token over to it correctly. Contact support@squawkvoice.ai for the API address for your account.
What the receiving agent sees
- Caller context — the caller’s number, partly hidden (for example
+1-415-***-1234; the full number is never shown, and the page says Unknown if there is none), and the length of the call up to the transfer, when it is available. - Summary — the AI-written summary and its key points, when one is available.
- Transcript — what the AI agent and the caller said, with times. If there isn’t one, the page says No transcript available.
How long it lasts
- The token works for 10 minutes from the transfer, whether or not anyone has opened it. A long wait in a queue can use that time up.
- It can be opened 5 times. Each time the page loads counts as one.
- No more than 60 requests a minute are accepted from one network address, which a large contact centre sharing one address could reach.
- As soon as the page opens it removes the token from the address bar. Refreshing it, or opening a bookmark, shows Screen pop unavailable. Open the link from the agent desktop again instead.
If the page doesn’t show the context
When Screen Pop can’t be sent
A problem with Screen Pop never stops a transfer from going ahead. SquawkVoice asks for the token just before it transfers the call, and the caller can hear silence for a few seconds while it waits. If the request is slow or fails, the transfer goes ahead without the token — or with a token that won’t open — and the receiving agent sees no context. For a fallback that doesn’t depend on the page, also turn on Inline SIP context headers.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, which is the region the SIP domain above belongs to.SIP Signaling
RTP Media
These IP ranges, and the SIP domain on this page, are specific to Twilio’s North America Virginia region. If your deployment uses a different region, the SIP domain differs too — contact support@squawkvoice.ai for the domain to use, and 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:- Email: support@squawkvoice.ai
- Documentation: Explore the guides in the sidebar for more platform details