SIP Trunk (Twilio, Telnyx)
There are two regimes in which the Phonic Voice Agent can communicate over telephone:
- Outbound Calls: The agent is the caller. The agent initiates calls to other phone numbers from a user-configured phone number.
- Inbound Calls: The agent is the callee. The agent receives calls from anyone at a user-configured phone number.
Phonic provides an easy way to use Phonic’s reserved phone numbers for performing both inbound and outbound calls. This guide is for configuring your own phone number with a SIP trunking provider like Twilio or Telnyx.
We will walk through SIP trunking configuration using Twilio in this demo, but the process should be very similar for other SIP trunking providers.
Outbound
To perform outbound calls, we can simply call the /conversations/sip/outbound_call endpoint with a properly configured phone number. Let’s walk through the configuration steps below.
First, let’s create a SIP trunk and connect it to our phone number. Before starting, make sure you have purchased a phone number on Twilio (see guide here).
-
Navigate to the Trunks page and click “Create a New Trunk”
-
Give it a friendly name. This name is for your identification purposes only.
-
Click on the “Termination” page in the side bar.
-
Configure the Termination SIP URI for this trunk. Record this URI somewhere, as it will be needed for initiating outbound calls.
-
Create a new credentials list and add it to the SIP trunk. Record the username and password that you chose, as these will also be needed for initiating outbound calls. This step is technically optional, but it is important for preventing your SIP trunk from being spoofed.
-
Click on the “Numbers” page in the side bar and add your number to the SIP trunk.
For more information on termination settings, refer to Twilio docs here.
Once you have a configured SIP trunk with your phone number, simply use the follow code to initiate the call! Remember to include your Termination URI, Username, and Password in the correct headers for verification. Also, make sure you set your config appropriately!
Inbound
To setup an agent to accept inbound calls, we can simply add one or more properly configured phone numbers to our agent. Let’s walk through the configuration steps below.
First, let’s create a SIP trunk and connect it to our phone number. Before starting, make sure you have purchased a phone number on Twilio (see guide here).
- Navigate to the Trunks page and click “Create a New Trunk”
- Give it a friendly name. This name is for your identification purposes only.
- Click on the “Origination” page in the side bar.
- Set the Origination URI of this SIP Trunk to
sip:2j1rahun317.sip.livekit.cloud - Click on the “Numbers” page in the side bar and add your number to the SIP trunk.
For more information on origination settings, refer to Twilio docs here.
Once you have a configured SIP trunk with your phone numbers, use the Phonic API to create or update an agent with { phone_number: "custom", custom_phone_numbers: [<your_phone_numbers>] }.
The agent will now be able to receive phone calls on any of the configured phone numbers.
You can use the configuration_endpoint agent parameter to customize the agent’s behavior based on the incoming phone number.
SIP Trunk Settings
If your provider requires a specific signaling transport or encrypted media, pass the optional sip object when adding a custom phone number. The settings apply to both inbound and outbound calls on that number. To change them later, remove the number and add it again.
transport:auto(default),udp,tcportls. This is the SIP signaling transport.X-Sip-Addressmust be a bare host or IP with an optional port (e.g.sip.example.com:5061) — a;transport=tlsparameter on the address is rejected, so set the transport here instead.media_encryption:disabled(default),allowedorrequired. This covers media (SRTP) only and is independent oftransport. Withrequired, calls that can’t negotiate SRTP fail rather than falling back to unencrypted media.
The same sip object can be passed per call to /conversations/sip/outbound_call.
Phone Call Transfers
If you intend to use the “transfer to phone number”, make sure to enable SIP REFER headers and PSTN transfers on your SIP Trunk. See this link for configuration on Twilio.
Showing the caller’s number on a transfer
A transfer tool with use_agent_phone_number: false presents the original caller’s number to the person you transfer to. On a custom trunk, how that works depends on how the transfer connects:
- Hand-off without DTMF (
keep_listening: false, nodtmf): your carrier redirects the call with a SIP REFER and keeps the caller’s number. No extra setup is needed. - Bridged transfer, or a hand-off with DTMF: Phonic places a new call to the destination through your trunk with the caller’s number as the caller ID. Carriers block that unless they can verify the call is a forward of a real incoming call, so your carrier needs the setup below.
If the carrier can’t verify the forward, Phonic places the transfer with the agent’s number instead. The transfer still connects; the destination just sees your number rather than the caller’s.
Twilio
Twilio verifies forwarded calls with a CallToken, which is a public beta on Elastic SIP Trunking.
- Request the beta for your Twilio account using the form linked from that page. There is no setting for it in the Twilio console.
- Once it is enabled, Twilio adds an
X-Twilio-CallTokenheader to each incoming trunk call. Phonic sends it back on the transfer automatically. - Make sure the termination URI you gave Phonic for this number belongs to the same Twilio account that receives the incoming calls. The token only works on the account that issued it.
See Twilio’s Trusted Calling with SHAKEN/STIR for background on why forwarded caller IDs need this.
Telnyx
Phonic adds a Diversion header naming your Telnyx number to the transfer. Telnyx matches it to the active incoming call and allows the caller’s number. The transfer must go out through the same Telnyx account that received the call. If Telnyx rejects the caller’s number, Phonic retries briefly and then falls back to the agent’s number.
Other providers
Phonic can only show the caller’s number on a bridged transfer through Twilio or Telnyx. On other providers the transfer uses the agent’s number, or you can use a hand-off without DTMF.