SessionPBX

Twilio

Twilio Elastic SIP Trunking connects to SessionPBX without registration. SessionPBX can read your Twilio account and fill in most of the trunk for you.

Twilio requires full international format, +E.164, in both directions.

Before you start

Create an Elastic SIP Trunk in the Twilio console if you do not already have one. Note its Termination SIP URI, which looks like yourtrunk.pstn.twilio.com.

Create an API key in Account → API keys & tokens. Use a standard API key, not your Auth Token: an Auth Token has full access to your account and can spend money, and it cannot be revoked separately.

You need three values:

Account SID, beginning AC
API Key SID, beginning SK
API Key secret, shown once when the key is created

Connect your Twilio account

Open the SessionPBX project and select Call Routing.
On SIP trunks, select Add trunk.
Name the trunk, then choose Twilio Elastic SIP Trunking as the Provider.
Enter the Account SID, API Key SID and API Key secret, then select Connect account.

SessionPBX reads your account and fills in:

your purchased phone numbers, as inbound numbers
the termination host from your Elastic SIP Trunk
Twilio’s signalling IP ranges, transport and port

Your credentials are used for this lookup only. They are not stored, and nothing in your Twilio account is changed.

A standard API key is enough. It cannot read the account’s friendly name, so the Account SID is shown instead — that is expected and nothing is wrong.

If you have more than one Twilio trunk

Accounts often have one trunk per region, for example a US trunk and a European one. SessionPBX lists them, and this trunk uses the one you select.

Regional trunks are separate services, so add a trunk for each and use Outbound number rules to route by prefix — +1 to the US trunk, +44 to the European one. The longest matching prefix wins.

Use Additional gateways only for hosts that are alternative routes to the same destinations. Gateways within one trunk are treated as interchangeable, so a call can leave by any of them.

If your trunks are not listed

Twilio scopes the trunk list to the project that issued the API key, and that is not always the account you are reading. A key created in a parent project lists a subaccount’s numbers perfectly well and sees none of its trunks.

When that happens SessionPBX shows a Trunk SID box. Open the trunk in the Twilio console, copy the SID beginning TK, paste it in and select Read the account again. Or create the API key in the project that owns the trunk.

You can also type the termination host yourself and carry on.

Let SessionPBX finish the setup

Finish the setup in Twilio for me is ticked by default. When the trunk is created, SessionPBX will:

add an origination URI on your Twilio trunk pointing at your region’s node, so inbound calls reach you
attach the numbers you selected to the trunk
add the node’s IP to a Twilio IP access control list, so Twilio accepts your outbound calls

Nothing else on your Twilio account is touched, and your credentials are used for these requests only. Every step checks what is already there first, so creating a second trunk against the same Twilio trunk changes nothing.

If a step fails — usually a key without permission for that resource — SessionPBX says which one and keeps going with the rest. The trunk is saved either way, and Try again repeats only what did not work.

Untick it if you would rather do the Twilio side yourself, and follow Finish in the Twilio console below.

Complete the trunk

Work through the remaining steps. The defaults suit most Twilio accounts.

Connection — host, port 5060 and UDP transport are filled in. Leave Direction on Both directions unless this trunk is one-way.
Authentication — By our IP address is filled in, with Twilio’s signalling ranges already listed. This is the direction Twilio calls us; the access control list SessionPBX creates is the other direction. Keep all of them: Twilio uses every edge for resiliency, so a shorter list works until an edge fails over. Choose Username and password instead if you configured a Twilio credential list.
Inbound — your numbers are listed. Remove any that should not route here.
Outbound — set Caller ID to a number on this Twilio account.

Select Create trunk.

Finish in the Twilio console

Only needed if you unticked Finish the setup in Twilio for me, or if a step reported a failure. Calls travel outbound only until this is done.

Open your Elastic SIP Trunk in Twilio.
Under Origination, add a SIP URI pointing at your SessionPBX region’s service address.
Under Numbers, associate the numbers you listed on the trunk.
Under Termination, add an IP access control list containing your node’s public IP.

Ask support for your region’s origination address and node IP if you do not have them.

Test

Call one of your Twilio numbers from an outside phone and confirm the right extensions ring.
Enable Outbound PSTN for one member, call a public number, and confirm two-way audio and the caller ID you set.

If outbound calls fail, check that the termination host matches your trunk exactly. If inbound calls never arrive, the origination URI in Twilio is the usual cause.