> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getthread.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice AI SIP Trunks & Caller ID

> Route Voice AI attendant call transfers through your own SIP trunk so your PBX sees the customer's caller ID and custom SIP headers on hand-off.

> [!NOTE]
>
> SIP Trunks & Caller ID is in beta and is enabled per workspace. Ask your Customer Success contact to turn it on for your workspace, until then the page won't appear.

## What is a SIP trunk in Thread?

By default, when a Voice AI attendant transfers a caller to your team, Thread passes the **original customer's phone number** through as the caller ID. You can add a SIP trunk connection to get additional context about the call through SIP headers and get the benefit of increased security.

Adding a SIP trunk lets Thread route that transfer through your own SIP-capable PBX, so:

* The transferred call arrives on your PBX over your own trunk, with the customer's number as the caller ID.
* Thread can attach **custom SIP headers** (name, company, PSA IDs, ticket number, call reason) that your PBX or wallboard can read.

SIP trunks are optional. Voice AI works without one. Add a trunk when you want richer call metadata delivered to your on-prem or cloud PBX (for example 3CX or Asterisk-based systems).

## Where to find it

Go to **Voice AI > SIP Trunks & Caller ID** in the admin app. If you don't see the tab, it isn't enabled for your workspace yet — ask your Customer Success contact.

## Add a SIP trunk

Select **Add SIP Trunk** to launch the stepped configuration form. You can move between steps freely: nothing is saved until you select **Save**.

**1. Trunk identity**

* **Name**: internal label for this trunk.
* **Transport**: pick the transport your PBX accepts:
  * **TLS**: encrypted signaling (recommended). Default port `5061`.
  * **TLS + SRTP**: encrypted signaling and media.
  * **TCP**: unencrypted signaling over TCP. Default port `5060`.
  * **UDP**: unencrypted signaling over UDP. Default port `5060`.
* **Host and port**: enter your PBX hostname and port separately. Thread combines them into `host:port` on save. Leave the port blank to use the transport default.
* **Country**: the country this trunk serves. Only attendant agents in the same country can be linked to it.

**2. Egress IPs**

Add both of the outbound IP ranges shown here to your SIP server's allowlist. Voice AI will place signaling from these ranges only — traffic from anything else should be rejected. Use the copy icon on each range.

**3. Credentials (optional)**

If your PBX requires SIP digest authentication, enter the **username** and **password**. Leave both blank for IP-based authentication.

**4. TLS certificate**

This step only appears for **TLS** or **TLS + SRTP** transports. Thread shows the LiveKit root CA:

* **Issuer** and **SHA-256 fingerprint** for verification.
* The full **PEM**: copy it and import it into your PBX's trusted CA store so your PBX will accept Thread's TLS handshake.
* **Refetch** re-loads the CA if you need the latest copy.

The certificate is environment-wide, not per-trunk. Import it once per PBX.

**5. Test connection**

Select **Test connection** to place a signaling probe through the trunk. Thread cancels the call immediately after your server responds. Possible results:

By default, Thread dials a reserved test number (`+15555550199`). If your PBX only accepts calls to DIDs it recognizes (for example 3CX), the probe can come back as a false auth failure even when the trunk itself is fine. To avoid this, select **Change destination number** and enter one of your existing DIDs in E.164 format so the test exercises a number your PBX already accepts. Leave it collapsed to use Thread's default.

| Status | Meaning | What to check |
| - | - | - |
| **Connection successful** | Thread reached your server and (if credentials were provided) authentication passed. | You're ready to save. |
| **Authentication failed** | Reached the server but credentials were rejected. | Confirm Thread's egress IPs are allowlisted and that the username and password match your PBX. If your PBX rejects unknown DIDs (for example 3CX), retry with a **Change destination number** value that matches one of your DIDs. |
| **Could not reach the trunk** | No response on the expected port. | Check the hostname, port, transport, and firewall. For TLS, make sure the CA from Step 4 is installed on the PBX. |
| **Test was inconclusive** | The probe itself failed. | Retry, or double-check the trunk configuration. |

Expand **Details** to see the raw SIP response for troubleshooting.

**6. Custom SIP headers**

Custom headers let you deliver caller and ticket metadata to your PBX on every transferred call. Enter a header name (Thread prefixes custom headers with `X-` for you) and pick a supported value from the dropdown:

* `caller_phone`
* `contact_name`
* `contact_company`
* `contact_match_type` (`by_phone_number`, `by_name_and_company`, or `unable_to_determine`)
* `psa_contact_id`, `psa_contact_company_id`, `psa_ticket_number`
* `call_reason`
* `correlation_id`

Headers set here apply to every agent linked to this trunk — you don't need to configure them per agent.

**P-Asserted-Identity** is added and locked by Thread. It carries the caller's number in the standard RFC 3325 name-addr form so PBXs (including 3CX) accept the call.

**7. Link agents**

Select the attendant agents that should route their outbound transfers through this trunk. Only attendants whose phone number's country matches the trunk's country are eligible. An agent can be linked to only one SIP trunk, so agents already linked to another trunk aren't offered here. To move an agent, unlink it from its current trunk first. Changing the trunk's country clears any linked agents.

## Edit and delete trunks

A trunk is active when it has at least one linked agent. There is no separate on/off toggle. Linked agents route their outbound transfers through the trunk, and a trunk with no linked agents isn't used.

Once at least one trunk exists, the list view shows each trunk as a card with:

* **Edit**: opens the stepped form pre-populated with the current values.
* **Delete**: asks for confirmation, then removes the trunk. Any linked agents fall back to Thread's default transfer path.

> [!TIP]
>
> Test the trunk before linking production agents to it. If a call fails on your side, unlink the affected agents or delete the trunk. Those agents then route transfers through Thread's default path while you troubleshoot.

## Frequently asked questions

> [accordion] Do I need a SIP trunk to use Voice AI?
>
> No. Voice AI attendants work without one, and caller-ID pass-through on transfers works by default. The trunk is only needed to route transfers over your own SIP trunk with custom SIP headers.

> [accordion] Which PBXs are supported?
>
> Any PBX that accepts a standard SIP trunk with the transports listed above. Verified integrations include 3CX and Asterisk-based systems.

> [accordion] Can one trunk serve multiple countries?
>
> No. A trunk is scoped to a single country, and only same-country attendant agents can be linked to it. Add one trunk per country if you operate in more than one.

> [accordion] How do I stop using a trunk without deleting it?
>
> Unlink all agents from the trunk. A trunk with no linked agents isn't used, and those agents fall back to Thread's default transfer path. To stop using the trunk permanently, delete it.

> [accordion] What happens if the trunk is unreachable during a live call?
>
> If the trunk is unreachable at the time of transfer, Voice AI falls back to Thread's default transfer path so the call still connects.


## Related topics

- [Voice AI Contact Mapping](https://docs.getthread.com/ai-agents/contact-mapping.md)
- [Forward your phone system to Voice AI](https://docs.getthread.com/ai-agents/connect-your-phone-system-to-voice-ai.md)
- [Phone system forwarding directory](https://docs.getthread.com/ai-agents/phone-system-forwarding-directory.md)
