Skip to main content

What a SIP trunk does

A Voice AI SIP trunk connects your PBX to Thread directly over SIP. Each trunk has two sides, and you can set up either one or both: Thread names each side from Thread’s point of view. On your PBX the names flip: Thread’s inbound trunk is a call your PBX places, and Thread’s outbound trunk is a call your PBX receives. SIP trunks are optional. Without one, callers reach the agent by dialing or being forwarded to its Thread number, and transfers go out over regular phone lines with the caller’s number passed through. For the 3CX settings on the PBX side, see Connect 3CX to Voice AI with a SIP trunk.

Where to find it

Go to Voice AI > SIP Trunks & Caller ID in the admin app and select Add SIP Trunk, or open an existing trunk to edit it. Nothing is saved until you select Save on the trunk page.

Add a SIP trunk

1

Name the trunk and pick its country

  • Internal name: a label your customers never see.
  • Country: only Voice AI agents with a number in this country can be linked to the trunk. The country can’t be changed after the trunk is created.
2

Set up the inbound side (optional)

Under Inbound trunk, select Set up trunk.
  1. Point your phone system to Thread. Copy Thread’s SIP address. Your PBX sends calls to it over TLS on port 5061, or over UDP or TCP on port 5060. Thread’s SIP address uses a wildcard certificate (*.sip.livekit.cloud), so a PBX that only accepts an exact-match certificate, such as 3CX, has to use port 5060. Set Media encryption to Required whenever your PBX supports SRTP: Thread then accepts only calls whose audio is encrypted. Allowed accepts encrypted and unencrypted audio, and Disabled accepts only unencrypted audio. Turn SRTP on in your PBX to match.
  2. Restrict who can call. Choose how Thread recognizes your PBX:
    • Allowed addresses: Thread accepts calls only from the IP addresses or CIDR blocks you list, one per line. Leave the list empty to accept calls from any address. Anyone who knows Thread’s SIP address and your agent’s number can then call it with any caller number, so list your PBX’s addresses when you can.
    • Username and password: your PBX answers a challenge on every call. Use this when your PBX is hosted and shares its IP address with other customers. These credentials are separate from any you set on the outbound side.
  3. Test connection (optional). Select Start listening and call the SIP address Thread shows from your PBX. Each call Thread accepts appears with its caller, number and headers, which confirms your address or credentials and media encryption work. Thread ends test calls right away, so your PBX may log them as busy. Thread only sees calls it accepts: if nothing appears, check the allowed addresses or credentials, that your PBX sends to port 5060, and that a rule routes the test number to the Thread trunk.
Inbound trunk settings at step 2, Restrict who can call, with Username and password chosen in the select, a username filled in and the password field below it

Choose how Thread recognizes your PBX

Inbound Test connection step listening, with the test number and SIP host in separate copy fields, a green banner saying Thread accepted the call and one received call showing time, from, to and display name

A call Thread accepted during an inbound test

Under Pass headers to your outbound trunk (optional), list SIP headers on the calls you send to Thread that you want copied onto the call when Thread transfers it back to you. Headers a call doesn’t carry are skipped. A header your outbound side already sets, such as P-Asserted-Identity, can’t be listed, and neither can headers that run the call itself or carry credentials, such as Via, Contact, Authorization or Session-Expires.Select Save to return to the trunk page.
3

Set up the outbound side (optional)

Under Outbound trunk, select Set up trunk and work through each step:
  1. Trunk identity. Pick the transport your PBX accepts and enter your PBX’s address. TLS+SRTP is recommended: it encrypts the call setup and the audio, and your PBX must accept SRTP. TLS encrypts the call setup only. Both default to port 5061; TCP and UDP encrypt neither and default to 5060. Leave the port blank to use the default.
  2. Add Thread’s SIP IPs to your allow list. Add all three IP ranges shown to your PBX’s allow list. Use the copy button next to each one.
  3. Username and password (optional). Enter them only if your PBX requires digest authentication for incoming calls.
  4. Install our TLS certificate. Shown for TLS only. Import the CA chain into your PBX’s trusted CA store so it accepts Thread’s TLS handshake. The certificate is the same for every trunk.
  5. Test connection. Enter a DID that your PBX routes to a person, then select Test connection. Thread places a call through the trunk and hangs up as soon as your PBX responds. When it succeeds, select Complete. If your PBX only accepts calls to numbers it recognizes, as 3CX does, testing against a DID it doesn’t know reports a failure even when the trunk is fine.
Below the steps, set the Custom SIP headers Thread adds to every transfer. Enter a header name (Thread adds the X- prefix) and pick a value: caller phone, contact name, contact company, contact match type, PSA contact ID, PSA contact company ID, PSA ticket number, call reason or correlation ID. P-Asserted-Identity is added and locked by Thread; it carries the caller’s number in the form PBXs such as 3CX accept.Select Save to return to the trunk page.
4

Link agents

Under Link SIP trunk(s) to agents, select Link agent and pick the attendant agents that use this trunk. Linked agents use every side that’s switched on. An agent can be linked to only one trunk, so agents on another trunk are listed as already assigned; unlink them there first. You can also pick an agent’s trunk under Use SIP Trunks in the agent’s settings, which moves it off any other trunk.
5

Save the trunk

Select Save. Each side you set up shows Configured, with a switch that turns on once an agent is linked.
Trunk settings page with the Inbound and Outbound trunk cards marked Configured with their switches on, and one linked agent with an Unlink agent button

Both sides of one SIP trunk

What changes when an inbound side goes live

Saving an inbound side with an agent linked moves that agent’s Thread phone numbers onto your trunk. From then on, Thread answers those numbers only for calls your PBX sends over the trunk. A call that reaches the number over the phone network won’t reach the agent, whether your PBX forwards it over PSTN or someone dials it directly. Send every caller from your PBX over the SIP trunk. Unlinking the agent moves its numbers back to Thread’s regular phone lines.
When a trunk has only one side, the agent uses Thread’s default path for the other direction:
  • Inbound only: callers arrive over SIP, and transfers dial the agent’s transfer number over regular phone lines.
  • Outbound only: callers dial the agent’s Thread number as usual, and transfers go to your PBX over SIP.

Add inbound to a trunk you already use

If a trunk already carries transfers to your PBX, open it, select Set up trunk under Inbound trunk, and complete the inbound steps above. Your outbound settings, custom headers and linked agents stay as they are. Point your PBX at Thread’s SIP address and route the agents’ numbers to it before you turn inbound on. The switch on the Inbound trunk card starts off, because the agents are so far linked only to the outbound side; turn it on and select Save on the trunk page, and the linked agents start using the inbound side. For 3CX, follow Add inbound to your existing Thread-3CX SIP trunk.

Edit, pause and delete trunks

A side carries calls while its switch is on and at least one agent is linked to the trunk.
  • Edit: open the trunk from the list, select Edit settings on a side, and save the trunk page when you’re done.
  • Turn one side off: switch it off on the trunk page and select Save. Its settings stay, so you can switch it back on later. Turning inbound off returns the agents’ numbers to Thread’s regular phone lines; turning outbound off sends their transfers over the default path. One side stays on while agents are linked.
  • Pause the trunk: from the trunk’s menu in the list, select Disconnect all agents. The trunk keeps its settings and carries no calls until you link an agent again.
  • Delete: from the trunk’s menu in the list, select Delete trunk. Its agents are disconnected first and go back to Thread’s default path.
Test a new trunk with one agent before linking the rest. If calls fail, unlink the agent and it goes back to Thread’s default path while you troubleshoot.

Frequently asked questions

No. Voice AI agents work without one, and the caller’s number is passed through on transfers by default. Add a trunk to keep calls on SIP in either direction and to deliver caller and ticket details as SIP headers.
Any PBX that can place and receive calls on a standard SIP trunk with the transports above. For step-by-step settings, see Connect 3CX to Voice AI with a SIP trunk.
No. A trunk serves a single country, and only agents with a number in that country can be linked to it. Add one trunk per country.
No. Thread doesn’t accept SIP registrations. Configure your PBX’s trunk to Thread without registration. With username and password, your PBX answers Thread’s challenge on each call instead.
Yes. On the trunk page, switch the side off and select Save. The side keeps its settings, so switching it back on restores it.