Skip to main content
A SIP Trunk channel allows you to connect your existing PBX or SBC directly to a VIVI AI agent over SIP. Incoming calls from your phone system are routed through a Twilio SIP Domain to VIVI, where a real-time voice AI agent handles the conversation. When the agent determines the caller must be transferred to a different extension or phone number, it transfers the call back to your PBX via SIP REFER. This channel is ideal for enterprises that want to front their existing phone system with an AI agent — handling common inquiries, collecting information, or routing callers — without changing their telephony infrastructure.

​
How It Works

Your PBX / SBC
    │
    │  SIP INVITE
    ▼
Twilio SIP Domain (vivi.sip.twilio.com)
    │
    │  Source IP validation
    ▼
AI Agent (real-time voice)
  1. Your PBX sends a SIP INVITE to the Twilio SIP Domain assigned to your channel.
  2. Twilio validates the incoming request using the source IP.
  3. VIVI identifies the channel by matching the source IP and the dialed extension, then connects the call to your configured AI agent.
  4. The agent converses with the caller using voice. When a transfer is needed, VIVI sends a SIP REFER back through Twilio to your PBX.

​
Prerequisites

Before setting up a SIP Trunk channel, make sure you have:
  • A PBX or SBC capable of sending SIP INVITE requests to an external SIP URI
  • The Fully Qualified Domain Name (FQDN) for your PBX
  • A VIVI agent with Realtime mode enabled
  • Network connectivity from your PBX to vivi.sip.twilio.com on port 5060 (UDP/TCP) or 5061 (TLS)
  • Your PBX must support the G.711 μ-law (PCMU) codec
TLS is strongly recommended. When you create a SIP Trunk channel, TLS on port 5061 is the default transport protocol. Only use UDP or TCP if your PBX does not support TLS.

​
Firewall Configuration

For SIP Trunk channels to work, your firewall must allow bidirectional traffic between your PBX/SBC and Twilio. This means permitting both outbound connections from your PBX and inbound connections from Twilio.

​
Outbound (Your PBX → Twilio)

Allow outbound traffic from your PBX to vivi.sip.twilio.com on the appropriate SIP port:
ProtocolPortWhen to allow
TLS5061Default and recommended
TCP5060If your PBX does not support TLS
UDP5060If your PBX does not support TLS or TCP

​
Inbound (Twilio → Your PBX)

Twilio must be able to reach your PBX for SIP REFER transfers and media (RTP) traffic. Allow inbound traffic from the following Twilio IP ranges: Signaling IPs — Allow inbound SIP on your PBX’s SIP port (5060 or 5061):
CIDRDescription
54.172.60.0/30Twilio SIP signaling (US East)
54.244.51.0/30Twilio SIP signaling (US West)
Media IPs — Allow inbound RTP/SRTP on your media port range (typically UDP 10000–60000):
CIDRDescription
168.86.128.0/18Twilio media servers
Both directions are required. If you only allow outbound traffic, initial calls will connect but transfers will fail because Twilio cannot send SIP REFER back to your PBX. If you only allow inbound traffic, your PBX cannot send the initial SIP INVITE.

​
Summary

DirectionTraffic TypeDestinationPorts
OutboundSIP signalingvivi.sip.twilio.com5061 (TLS) or 5060 (TCP/UDP)
InboundSIP signaling (REFER)Your PBXYour PBX SIP port
InboundMedia (RTP)Your PBXYour media port range

​
Setting Up a SIP Trunk Channel

​
Step 1: Create the Channel

In the VIVI portal, navigate to Channels and create a new SIP Trunk channel. You will need to provide:
FieldDescription
Origin HostThe FQDN or public IP address of your PBX/SBC. For example sbc.yourcompany.com or 203.0.113.10
Origin PortThe SIP port your PBX sends from. Default is 5061 for TLS.
Origin ProtocolTransport protocol: TLS, TCP, or UDP. Default is TLS
Extension / NumberThe extension number your PBX dials to reach this agent. 1–20 digits, numeric only, for example 1001
Once created, VIVI will resolve your Origin Host to its IP addresses and whitelist them to receive calls from.

​
Step 2: Note Your Destination SIP URI

After provisioning completes, the channel detail page displays your destination details:
FieldValue
Destination Hostvivi.sip.twilio.com
Destination Port5061 (TLS) or 5060 (UDP/TCP)
Destination ProtocolMatches your selected transport
This is the SIP URI your PBX should send INVITEs to: 
sip:<extension>@vivi.sip.twilio.com:<port>;transport=<protocol>
For example, to reach extension 1001 over TLS: 
sip:1001@vivi.sip.twilio.com:5061;transport=tls

​
Step 3: Configure Your PBX

On your PBX or SBC, create an outbound SIP trunk pointing to the Destination SIP URI. The specific steps vary by vendor, but generally you need to:
  1. Create a SIP trunk with the destination host and port from Step 2
  2. Set the transport protocol to match (TLS recommended)
  3. Configure a dial plan or route that sends calls for the target extension to this trunk
  4. Ensure your firewall allows outbound SIP traffic to vivi.sip.twilio.com on the configured port
Authentication is IP-based only. There are no usernames or passwords to configure. VIVI validates incoming SIP INVITEs by checking the source IP. Make sure your PBX sends traffic from the IP address(es) that match your configured Origin Host.

​
Step 4: Assign an Agent

In the agent settings, assign the SIP channel to the agent. The agent must have Realtime mode enabled, otherwise you won’t be able to assign it.

​
SIP INVITE Format

When your PBX sends a SIP INVITE, VIVI uses the following fields to identify the channel and route the call:
SIP FieldWhat VIVI ExpectsExample
Source IPMust match one of the channel’s authorized origin IPs.203.0.113.10
To (Request-URI)The user part is extracted as the extension. Must match one of the channel’s configured numbers.sip:1001@vivi.sip.twilio.com
FromPassed to the AI agent as caller identification.sip:+14155551234@sbc.yourcompany.com

​
How Calls Are Matched

VIVI identifies which channel should handle an incoming call by matching both:
  1. Source IP — The IP address your PBX sends from must be authorized for the channel
  2. Dialed extension — The user part of the To URI must match one of the channel’s configured numbers
If either does not match, or if the matched channel has no agent assigned, the call is rejected with a SIP 603 Decline.

​
Extension Format

The To URI should follow standard SIP URI format. VIVI extracts the extension by parsing everything between sip: and @:
To HeaderExtracted Extension
sip:1001@vivi.sip.twilio.com1001
sip:5551234@vivi.sip.twilio.com5551234
Extensions must be numeric only (1–20 digits). Alphanumeric SIP usernames are not supported.

​
Call Transfers

When the AI agent determines that a caller should be transferred, VIVI initiates the transfer using SIP REFER.

​
How It Works

SIP REFER instructs your PBX or SBC to redirect the existing call — VIVI does not create a new outbound call: 
VIVI AI Agent
    │
    │  triggers transfer
    ▼
Twilio
    │
    │  SIP REFER
    ▼
Your PBX / SBC
    │
    │  routes call internally
    ▼
Target extension answers
  1. The AI agent triggers a transfer (via a configured transfer destination or DTMF input)
  2. Twilio sends a SIP REFER to your PBX with the target SIP URI
  3. Your PBX processes the REFER and routes the call to the target extension
  4. Your PBX sends a NOTIFY back to Twilio with the transfer outcome

​
Refer-To URI

The REFER message includes a Refer-To header with the target SIP URI. This URI is constructed from your channel’s origin configuration: 
sip:<target-extension>@<origin-host>:<origin-port>;transport=<origin-protocol>
For example, if your channel is configured with originHost=sbc.yourcompany.com, originPort=5061, originProtocol=TLS, and the transfer target is extension 2001: 
sip:2001@sbc.yourcompany.com:5061;transport=tls

​
PBX Requirements for Transfers

For SIP REFER transfers to work, your PBX must:
  1. Accept SIP REFER requests from Twilio’s IP ranges
  2. Process the Refer-To header and route the call to the specified extension
  3. Send NOTIFY messages back to Twilio with the transfer outcome (per RFC 3515)

​
Configuring Transfer Destinations

Transfer destinations define where the AI agent can transfer calls. Each destination has:
FieldDescriptionExample
NameA human-readable label for the destination (optional).Front Desk
NumberThe target extension on your PBX.2001
TriggerA phrase or keyword the agent recognizes to initiate the transfer.when user wants to talk to front desk

​
Managing Origin IPs

VIVI resolves your Origin Host to IP addresses automatically via DNS during provisioning. These IPs are authorized to send calls to your channel.

​
When to Update IPs

You may need to manually update origin IPs if:
  • Your PBX IP address changes and DNS has not propagated
  • Your PBX sends traffic from multiple IPs not covered by the FQDN
  • You want to add a secondary PBX or SBC as a backup origin

​
How to Update

In the channel settings, you can view the current list of resolved IPs and add or remove entries. When you update the Origin Host, VIVI will re-resolve the FQDN and update the authorized IPs accordingly.
IP changes may take a few moments to propagate. During this window, calls from the new IP may be rejected. Plan IP changes during low-traffic periods.

​
Troubleshooting

  • Check your origin IPs. The source IP of your SIP INVITE must match one of the authorized IPs in the channel. Go to channel settings and verify the IP list.
  • Check the dialed extension. The user part of the To header must match one of the channel’s configured numbers.
  • Check agent assignment. The channel must have a Realtime-enabled agent assigned.
  • Check codec support. Ensure your PBX supports G.711 μ-law (PCMU).
  • Check firewall rules. Ensure your firewall allows inbound media from Twilio’s media IP range (168.86.128.0/18) on your RTP port range. See the Firewall Configuration section above.
  • Check PBX REFER support. Your PBX must accept and process SIP REFER requests from Twilio.
  • Check firewall rules. Your firewall must allow inbound SIP from Twilio’s signaling IPs (54.172.60.0/30 and 54.244.51.0/30) to your PBX’s SIP port. Without this, REFER messages cannot reach your PBX. See the Firewall Configuration section above.
  • Check the Refer-To URI. The transfer target URI is built from your channel’s origin host, port, and protocol. Ensure your PBX can route calls to the target extension at that address.
  • Check NOTIFY responses. Your PBX should send NOTIFY messages back to Twilio per RFC 3515.
  • Verify the FQDN. Ensure your Origin Host resolves to at least one IPv4 address.
  • Check DNS propagation. If you recently updated DNS records, allow time for propagation.
  • Use an IP address directly. If DNS is unreliable, you can enter the IP address as the Origin Host and manually manage the origin IP list.