Skip to main content
A connection file holds environment variable names. This page is about the values behind them: where each one lives in your Twilio account, and which key it belongs to. It also covers the console setup those values assume, because a correct connection file over a half-configured trunk still gets you nothing. On this page:
Unmute never buys a number, creates a trunk, or changes anything on your carrier account, at compile time or afterward. Every value below is one you set yourself, in the Twilio Console.

​
Start with the route

Twilio reaches an agent three ways, and they need different values. Find your row first, then read only the parts this page marks for it. The two groups are different credentials, not two names for one thing. The account trio identifies your account to Twilio’s REST API. The four SIP values are one trunk’s own dial-out settings, and they live in a different part of the console.

​
Every key a connection takes

Three keys. The first two pick the route, and the third names the variables that hold its values.
​
sip | connector | cloud-websocket | daily-sip
required
The mechanism that carries the call. It decides which environment keys the file accepts, so changing it changes the group of values you need.
​
twilio | telnyx | plivo
required
The carrier account behind the route. twilio on every route on this page.
​
route key to environment variable name
Which variable holds each value. The keys on the left are fixed by the route: account_sid, auth_token and from_number for the account trio, sip_address, sip_username, sip_password and from_number for the SIP route. A key from another route is refused, and the refusal lists the set this route accepts.
The names on the right are yours, and each one is UPPER_SNAKE: an uppercase letter, then only uppercase letters, digits and underscores. The compiler never reads a value, so a package with connections validates and compiles with no credentials present anywhere.

​
1. Get a voice-capable number

Phone Numbers, Manage, Buy a number, with the Voice capability. Skip this if you already own the number you want the agent to use. Whatever you buy or already own is the value of from_number, or SIP_FROM_NUMBER on the SIP route. It is also the caller identity the person you dial sees. Voice capability is the whole requirement on it. Write it in E.164 form: a plus, the country code, then the rest, no spaces.

​
Give each route its own number

A number attached to a SIP trunk ignores its voice configuration completely, and does so silently. So one number cannot serve a TwiML Bin and a SIP trunk at the same time. If you want both routes live, buy a second number: You can also swap a single number back and forth. Two numbers is less work after the first day.

​
2. Get the values your route needs

Read the half your row in Start with the route points at, and skip the other one.

​
The account trio

For Pipecat cloud-websocket and the LiveKit connector. Both talk to Twilio’s REST API in your name, so they need the account credentials.
connections/twilio_voice.yaml
The names on the right are yours to choose. Those three are what every Twilio example in the repository uses, so one .env drives all of them.

​
The four SIP values

For the LiveKit sip route. All four come off one Elastic SIP Trunk.
connections/twilio_sip.yaml
Setting the trunk up is a console walkthrough of its own, and it lives on LiveKit over Twilio. Two settings on that trunk decide whether a transfer works: Call Transfer (SIP REFER) with Enable PSTN Transfer, and the caller ID below.

​
3. Point the number at your agent

Having the values is not the same as routing the calls. Each route points the number at something different, and this is the part to get right. The SIP row is the one people miss, because you attach the number from inside the trunk and not from the number’s own page. Attach the number to the trunk has the console path. On cloud-websocket there is no URL of yours to configure, because nothing of yours is hosted. Your build’s generated README dictates the exact markup, including the regional stream address, which comes from the region in your targets.yaml. Pipecat over Twilio walks it, including the organisation slug that is the most common thing to get wrong.
Take the number off any SIP trunk before using it on one of the webhook routes. A number attached to a trunk ignores its voice configuration completely, and does so silently, so the markup or webhook you set would never be consulted.

​
4. Declare the names in your package

Two files, and neither holds a value:
agent.yaml
Every name your connection maps belongs in secrets: too. That is what puts it in the generated .env.example and in the startup check. The values go in .env locally, and in your platform’s secret store for a deployment.
A name you declare and never set is not caught at compile time. It is caught on the call, and the caller hears ringing that never ends. See the call rings and nobody answers.
Your build’s build/<target>/README.md is the authority for your own route. It was generated from your package, so it already names your region and your number.

​
Caller ID for a transfer target

A cold transfer is a SIP REFER: Twilio receives it and places a new call to the destination. The trunk decides what caller ID that new call presents, and the two choices behave very differently. Transferee is the nicer behaviour, because the person receiving the transfer sees the customer rather than your own line. It only works where the receiving carrier tolerates a caller ID that belongs to nobody on your account. Present a Spanish mobile number from a UK trunk to a Spanish carrier and it is rejected on the spot. How that failure looks, so you recognise it rather than debugging your agent:
  • The agent logs cold transfer failed after 0s: SIP call failed: 486 Busy Here.
  • Twilio’s call log shows a child call under the original call, with the original caller’s number in From, status Busy, duration 0 sec, cost blank, and no PCAP.
Zero seconds and no cost means the leg was rejected as it was offered and never reached the destination, so nothing rang and nobody was busy. Switch the trunk to Transferor and place the call again. A genuine busy signal costs time and money, and the record shows both.

​
If your trunk is in a Twilio Region

Twilio can hold resources in a region such as Ireland (IE1) rather than in the default one. If you set a number’s Active Region and create the trunk there, three things change:
  • The trunk gets a SID that the default API cannot see. A lookup returns 404 not found even though the console shows the trunk.
  • Regional endpoints such as api.dublin.ie1.twilio.com need regional API credentials. Your account SID and auth token get 401 Authenticate there.
  • The number’s Active Region and its trunk must be in the same region, and the console only shows you the configuration for the region you are viewing.
None of this changes what Unmute generates. It changes what you can inspect, and which console view tells you the truth, so note the region before you start comparing settings against a guide.

​
Where to go next

LiveKit over Twilio

The sip route end to end: the trunk, the two records, and the failures.

Pipecat over Twilio

The cloud-websocket route end to end.

connections/<name>.yaml

The file these values fill.

Transfers on LiveKit

Hand the caller to a person.