Custom SIP headers, X-Fish-Session-Id and sip_call_id for BYO SIP numbers

agents/monitor/conversation-history.mdx

@@ -4,9 +4,9 @@
 icon: "clock-rotate-left"
 ---
 
 Every production session your agents handle (from the API, the console, [public agents](/agents/deploy/public-agents), or [phone calls](/agents/telephony/inbound-calls)) is queryable over REST: a lightweight list for browsing, a merged timeline of messages and tool activity per session, and per-speaker recordings when the agent [records audio](#what-gets-stored). You can query a session while the call is still in progress.
 
 This is a server-side API: authenticate with your API key. The client SDKs deliberately expose no history interface; fetch history from your backend and pass it to your frontend as needed.
 
 ## What gets stored
 
@@ -58,18 +58,19 @@
       "source": "phone",
       "caller_number": "+15551234567",
       "dialed_number": "+14155550100",
+      "sip_call_id": "7f3a9c@sbc.example.com",
       "started_at": "2026-07-22T09:14:02Z",
       "ended_at": "2026-07-22T09:16:05Z",
       "duration_seconds": 123,
       "metadata": { "crm_ticket": "T-4821" }
     }
   ],
   "has_more": true,
   "next_cursor": "…"
 }
 ```
 
-`caller_number` and `dialed_number` are set for phone sessions only (E.164) and are `null` for web sessions. `name` is the display name you passed when creating the session (`null` when omitted), and `metadata` echoes back whatever you attached when creating the session.
+`caller_number` and `dialed_number` are set for phone sessions only (E.164) and are `null` for web sessions. `sip_call_id` is the SIP `Call-ID` of the call's INVITE. It is `null` on web sessions and on outbound calls that were never answered. See [Match calls with your SIP records](/agents/telephony/byo-sip#match-calls-with-your-sip-records). `name` is the display name you passed when creating the session (`null` when omitted), and `metadata` echoes back whatever you attached when creating the session.
 
 ### Status and end reason
 
@@ -101,6 +102,7 @@
 | `status`                           | One of `pending`, `active`, `completed`, `failed`, `unknown`; comma-separate values to match several |
 | `end_reason`                       | One or more of the `end_reason` values above, comma-separated                                        |
 | `caller_number`                    | Exact match on the caller's E.164 number; a bare number gets `+` prepended automatically              |
+| `sip_call_id`                      | Exact match on the SIP `Call-ID` of the call's INVITE, for looking up the session behind a carrier CDR entry              |
 | `created_after` / `created_before` | ISO 8601 timestamps                                                                                   |
 
 <Note>
@@ -189,7 +191,7 @@
 
 Details worth knowing:
 
 - **Role vocabulary**: the history API's `assistant` is the same speaker the [SDK's live events](/agents/deploy/web-sdk) call `agent`.
 - **Order**: items are sorted by `created_at` ascending; a `tool_result`'s timestamp is its completion time, so long-running tools appear where they actually finished, with messages in between. Items sharing a timestamp order `message`, then `tool_call`, then `tool_result`.
 - **`tool_source`**: where the tool ran, one of `client`, `webhook`, `builtin` (platform tools such as call transfer and hang-up), `mcp` (tools from a connected MCP server), `background` (work the agent delegated to a background task), or `unknown` (calls recorded before source attribution). Treat it as an open set. See [Tools](/agents/build/tools).
 - **Payloads**: `input` and `output` are JSON strings, symmetric with the live SDK events, so one parser covers both. `output` and `error` are stored up to 256 KB; beyond that the text is cut and `output_truncated` is `true`.

agents/monitor/webhooks.mdx

@@ -105,16 +105,16 @@
     "branch_id": "b7d4…",
     "source": "phone",
     "status": "completed",
     "end_reason": "user_hangup",
     "conversation_started_at": "2026-07-23T12:01:12Z",
     "conversation_ended_at": "2026-07-23T12:04:16Z",
     "duration_seconds": 184,
     "end_user_id": "customer-42",
     "metadata": { "order_ref": "SO-1042" },
     "agent_name": "Support agent",
     "config_hash": "sha256:9c41…"
   },
   "ended_reason": "user_hangup"
 }
 ```
 
@@ -167,6 +167,9 @@
     "direction": "outbound",
     "dial_status": "answered",
     "answered_by": "human",
+    "caller_number": "+15551234567",
+    "dialed_number": "+14155550100",
+    "sip_call_id": "7f3a9c@sbc.example.com",
     "batch_call_id": null,
     "conversation_started_at": "2026-07-23T12:01:12Z",
     "conversation_ended_at": null,
@@ -185,6 +188,8 @@
 
 `dial_status` is `answered`, `busy`, `no_answer`, or `failed`. `answered_by` is deprecated: answering-machine detection has been removed, so it is `unknown` once the call is answered and `null` before (older events may carry `human` or `voicemail`). Both facts also appear on the session, alongside `direction` (`inbound` or `outbound`) and `batch_call_id` (reserved, always `null` today); these session fields are present in every webhook payload, with the dial fields `null` on inbound sessions. The `phone_call.dial_finished` snapshot is taken when the dial resolves, so on an answered call `conversation_ended_at` and `duration_seconds` are still `null`. The final numbers arrive with `call.ended`.
 
+`caller_number`, `dialed_number` and `sip_call_id` carry the same values as on the [sessions API](/agents/monitor/conversation-history): the E.164 numbers of the call (person-centric on outbound calls, so `caller_number` is the party you dialed) and the SIP `Call-ID` of the call's INVITE. All three are empty strings on web sessions, and `sip_call_id` is also empty on an unanswered outbound dial. How to use it against your carrier's records: [Match calls with your SIP records](/agents/telephony/byo-sip#match-calls-with-your-sip-records).
+
 `end_user_id` and `metadata` are echoed exactly as you set them when creating the session. Use them to correlate the event with records in your own system. `branch_id` is an internal configuration-lineage identifier and is safe to ignore. What lands in `summary`, `data`, and `criteria_results` is defined by your [analysis configuration](/agents/monitor/post-call-analysis).
 
 The example shows a `completed` analysis. `analysis.status` can also be `skipped` (nothing to analyze: the caller never spoke, or analysis is disabled) or `error` (the run failed, with the cause in `analysis.error`); both arrive with `summary: null` and empty `data` / `criteria_results`. Check the status before reading results.
@@ -275,14 +280,14 @@
 | Fan-out   | Every configured endpoint receives every event                                                                    |
 | Guarantee | At-least-once, per endpoint                                                                                       |
 | Timeout   | 10 seconds per attempt                                                                                            |
 | Retries   | 2 after the first attempt (3 attempts total) per endpoint, with backoff of 1s / 5s, then that delivery is dropped |
 | Ordering  | `phone_call.dial_finished` (outbound only) before `call.ended` before `call.analyzed` for the same session        |
 
 Endpoints are delivered in parallel and independently: each gets its own attempts, its own retry budget, and its own signature keyed with its own secret. An endpoint that is down and exhausts all three attempts has no effect on the others.
 
 Respond with a `2xx` status within the timeout; a `500` response or a timed-out request counts as a failed attempt. Acknowledge first and process asynchronously. Slow handlers burn their own retry budget.
 
 **Idempotency.** At-least-once delivery means the same event can arrive more than once. Retries of one delivery carry an identical body, so dedupe `call.ended` and `phone_call.dial_finished` on (`event`, `session.id`), and `call.analyzed` on (`event`, `session.id`, `analysis.finished_at`). The extra element matters because a skipped or failed analysis can be re-run from the console: the recovered result arrives as a fresh `call.analyzed` with a newer `finished_at`, superseding the earlier one.
 
 <Note>
   [Preview calls](/agents/test/preview-calls) made from the Builder never
@@ -336,11 +341,11 @@
 }
 ```
 
 `caller_number` and `dialed_number` are E.164. `caller_number` is an empty string when the carrier withholds the caller's number, and `twilio_call_sid` is empty when the call did not come through a Twilio number.
 
 ### Response
 
 Respond with a `2xx` status and a JSON object whose `dynamic_variables` follow the same rules as on session creation: names match `[A-Za-z][A-Za-z0-9_]*`, values are strings (up to 1,000 characters), numbers, or booleans, and at most 50 entries are read.
 
 ```json Response
 {
@@ -372,7 +377,7 @@
 
 ## Auto-ticket unresolved calls
 
 `call.analyzed` closes the loop on conversations the agent couldn't: judge every call with a success criterion, and open a ticket in your helpdesk whenever the verdict isn't `success`.
 
 First give the agent's [analysis configuration](/agents/monitor/post-call-analysis) a criterion that captures resolution:
 
@@ -493,11 +498,11 @@
 
 </CodeGroup>
 
 `verifyWebhook` is the function from [Verify the signature](#verify-the-signature); `openTicket` stands in for your helpdesk's API. Escalating on anything but `success` includes `unknown` verdicts: the model couldn't judge the call, which usually deserves human eyes too. Tighten the check to `failure` only if unknowns prove noisy.
 
 Edges worth handling:
 
 - Calls with nothing to analyze arrive with `analysis.status: "skipped"`. The handler above tickets them as unjudged, so every call reaches the helpdesk without also watching `call.ended`. Drop that branch if silent calls don't belong in your queue.
 - Payloads carry no transcript. To include one in the ticket, fetch `GET /v1/agent/sessions/{session_id}` from your handler. See [conversation history](/agents/monitor/conversation-history).
 - Set `end_user_id` and `metadata` when creating sessions so tickets attach to the right customer record without a lookup.
 

agents/telephony/byo-sip.mdx

@@ -6,12 +6,14 @@
 
 If your numbers already live at a carrier, you can connect them to your agents without porting anything. Point the carrier's SIP trunk at Fish Audio and import the number: it stays with your carrier, who keeps billing you for the telephone-network legs, and on Fish Audio the calls bill as ordinary agent sessions. Imported numbers carry no monthly rental and no telephony charges of any kind: no phone surcharge, no transfer fees; the call bills like a web session.
 
 This works with any carrier or PBX that speaks SIP trunking: Twilio Elastic SIP Trunking, Asterisk or FreePBX, and most SIP providers. It is also the only way to use non-US/CA numbers, which the purchasable inventory does not cover.
 
 ## How it works
 
-- **Inbound**: your carrier routes calls for the number over its trunk to Fish Audio's SIP endpoint. The platform matches the dialed number and hands the call to the agent bound to it; from there it is a normal [inbound call](/agents/telephony/inbound-calls).
-- **Outbound** (optional): give the import a termination host and the platform can also place calls from the number. Outbound calls and warm-transfer consult legs dial out through your trunk, with the imported number as the caller ID.
+A SIP trunk has two directions, and carriers name them from the carrier's point of view. **Origination** is traffic your carrier originates towards Fish Audio: an inbound call. **Termination** is traffic your carrier terminates for Fish Audio: an outbound call the platform hands to your carrier or PBX to complete. Twilio's trunk configuration uses the same two words, and so do the fields below.
+
+- **Inbound (origination)**: your carrier routes calls for the number over its trunk to Fish Audio's SIP endpoint. The platform matches the dialed number and hands the call to the agent bound to it. From there it is a normal [inbound call](/agents/telephony/inbound-calls).
+- **Outbound (termination)**, optional: give the import a termination host and the platform can also place calls from the number. Outbound calls and warm-transfer consult legs dial out through your trunk, with the imported number as the caller ID. You can also attach custom SIP headers that every call through the termination carries, for routing hints or tenant identification on your PBX.
 
 The SIP endpoint to point your trunk at:
 
@@ -28,7 +30,7 @@
 
 ### In the console
 
-On the workspace **Phone numbers** page, choose **Import number**. Enter the number in E.164 format, set at least one inbound authentication factor, and optionally fill in the **Outbound calling (termination)** section. The same form is available later from the number's row menu as **Edit configuration**.
+On the workspace **Phone numbers** page, choose **Import number**. Enter the number in E.164 format, set at least one inbound authentication factor, and optionally fill in the **Outbound calling (termination)** section, including any **Custom SIP headers** (one `X-Name: value` per line). The same form is available later from the number's row menu as **Edit configuration**.
 
 ### Through the API
 
@@ -48,7 +50,8 @@
     "termination_uri": "pbx.example.com",
     "termination_transport": "tcp",
     "termination_auth_username": "fish-outbound",
-    "termination_auth_password": "another-long-password"
+    "termination_auth_password": "another-long-password",
+    "termination_headers": { "X-Customer-Id": "acme" }
   }'
 ```
 
@@ -67,6 +70,7 @@
 | `termination_transport`     | `auto` (default), `udp`, `tcp`, or `tls`.                                                                                                  |
 | `termination_auth_username` | Optional digest username for your termination; requires the password and a `termination_uri`.                                              |
 | `termination_auth_password` | The matching digest password.                                                                                                              |
+| `termination_headers`       | Optional: custom `X-` headers for every call through the termination, up to 20; see [Custom SIP headers](#custom-sip-headers).             |
 
 At least one inbound factor (digest credentials and/or allowed addresses) is required; a `422` reports what is missing. A `409` means the number is already on the platform. A `502` means trunk provisioning failed; the number stays visible with status `error` and is safe to release and retry.
 
@@ -80,30 +84,30 @@
 The SIP endpoint is shared, so an import must prove that calls really come from your trunk:
 
 - **Digest credentials**: the platform challenges your trunk and verifies the username and password. Use this whenever your carrier or PBX answers digest challenges (Asterisk, FreePBX, most SIP providers).
 - **Allowed source addresses**: calls are only accepted from the listed IPs or CIDR ranges. Use this for carriers that do not authenticate their origination traffic; Twilio Elastic SIP Trunking is one, so for Twilio this is the required factor.
 
 Set both when your carrier supports it.
 
 ## Carrier walkthroughs
 
 ### Twilio Elastic SIP Trunking
 
 <Steps>
   <Step title="Create a trunk">
     In the Twilio console, under **Elastic SIP Trunking**, create a trunk (or
     reuse an existing one).
   </Step>
   <Step title="Point origination at Fish Audio">
     Add an origination URI: `sip:1pv316az391.sip.livekit.cloud;transport=tcp`.
   </Step>
   <Step title="Attach your number">
     On the trunk's **Numbers** tab, add the phone number. Twilio routes its
     calls through the trunk from then on.
   </Step>
   <Step title="Import on Fish Audio">
     Twilio's origination does not answer digest challenges, so authenticate by
     source address: allow Twilio's published signaling IP ranges for the regions
     you use (see [Twilio's IP address
     list](https://www.twilio.com/docs/sip-trunking/ip-addresses)). In the
     console, the **Twilio Elastic SIP Trunking preset** button fills the ranges
     and sets the transport for you.
@@ -113,19 +117,19 @@
     (`yourprefix.pstn.twilio.com`) and attach a **Credential List**. Pass the
     host as `termination_uri` and the credentials as `termination_auth_username`
     and `termination_auth_password`. Credentials are required here: Fish Audio's
     outbound traffic does not come from fixed IPs, so Twilio IP access control
     lists cannot authorize it.
   </Step>
   <Step title="Allow transfers (optional)">
     For [cold transfers](/agents/telephony/transfers), enable **Call Transfer
     (SIP REFER)** in the trunk's settings so Twilio honors the handoff.
   </Step>
 </Steps>
 
 ### Asterisk, FreePBX, and other SIP platforms
 
 - Route the number's inbound calls to `sip:1pv316az391.sip.livekit.cloud;transport=tcp`.
 - Configure digest credentials on the trunk and pass the same pair as `inbound_auth_username` and `inbound_auth_password`; add your PBX's public IPs to `inbound_allowed_addresses` for defense in depth.
 - For outbound, expose a termination host reachable from the internet and pass it as `termination_uri`, with digest credentials if your PBX requires registration or authentication.
 
 ## Outbound calls and transfers
@@ -141,6 +145,65 @@
 
 The number object reports this as `supports_outbound`. Place calls with the same API as purchased numbers; see [Outbound calls](/agents/telephony/outbound-calls).
 
+### Custom SIP headers
+
+`termination_headers` lets you tag every INVITE the platform sends through your termination, for example to identify the tenant or pick a route on your PBX:
+
+```json
+"termination_headers": {
+  "X-Customer-Id": "acme",
+  "X-Route-Hint": "eu-west"
+}
+```
+
+The headers ride along on outbound calls and on warm-transfer consult legs, since both dial through the termination. Cold transfers hand the call off on the inbound leg and do not carry them. Names must be `X-` tokens or `User-to-User`, so the request's own fields (`From`, `To`, `Via`) cannot be overridden, and `X-Fish-` is reserved for headers the platform sets itself. Values are 1 to 1024 printable ASCII characters (128 for `User-to-User`). Header names are case-insensitive, so a map with two spellings of the same name is rejected.
+
+Values that change per call, such as a campaign or account id, go on the call instead: [`sip_headers`](/agents/telephony/outbound-calls#per-call-sip-headers) on the outbound call request is merged over these number-level headers. For matching calls to sessions you do not need a header of your own; see [Match calls with your SIP records](#match-calls-with-your-sip-records).
+
+## Match calls with your SIP records
+
+Your carrier, SBC or PBX keeps its own record of every call: a CDR, a log line, a recording file. Two identifiers let you line those records up with Fish Audio sessions, one in each direction, and neither needs any configuration.
+
+| Identifier          | What it is                                                                                                                           | Where you read it                                                                                                                                                       |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sip_call_id`       | The SIP `Call-ID` of the call's INVITE, the value the SIP world uses as the identity of one call. Your SIP records carry it already. | On the session, from `GET /v1/agent/sessions/{session_id}`, as a filter on the sessions list (`?sip_call_id=`), and in the `session` object of every post-call webhook. |
+| `X-Fish-Session-Id` | The Fish Audio session id, sent as a header on every INVITE and REFER the platform places through your trunk.                        | In your own SIP records, if your SBC or PBX logs custom headers.                                                                                                        |
+
+Which one you use depends on where you start:
+
+- **From a Fish Audio webhook to your records**: read `sip_call_id` from the webhook's `session` object and look it up in your CDR. This works without any change on your side, because every SIP system already records `Call-ID`.
+- **From your records to Fish Audio**: take the `Call-ID` from your CDR and list sessions with `GET /v1/agent/sessions?sip_call_id=…`, which returns the matching session. If your SBC logs custom headers, `X-Fish-Session-Id` from the INVITE gives you the session id directly.
+
+When each identifier is present:
+
+| Call                          | `sip_call_id` on the session           | `X-Fish-Session-Id` in the INVITE   |
+| ----------------------------- | -------------------------------------- | ----------------------------------- |
+| Inbound call                  | Yes, from your carrier's INVITE        | Not applicable: the INVITE is yours |
+| Outbound call, answered       | Yes, from the INVITE the platform sent | Yes                                 |
+| Outbound call, not answered   | `null`: no call was completed          | Yes, on the INVITE that was refused |
+| Warm transfer consult leg     | Not exposed separately                 | Yes, on the consult INVITE          |
+| Cold transfer to a SIP target | Not applicable                         | Yes, as a header on the REFER       |
+
+The `X-Fish-Session-Id` header is only sent through your own trunk. Calls from platform-purchased numbers terminate on the platform's carrier and carry no such header, but `sip_call_id` is still exposed for them.
+
+For your own business keys, such as a campaign or tenant id, add [custom SIP headers](#custom-sip-headers) on the number or [per call](/agents/telephony/outbound-calls#per-call-sip-headers). They complement the two identifiers above rather than replace them: a business key tells you which campaign a call belonged to, the identifiers tell you which call it was.
+
+A `phone_call.dial_finished` payload carries everything needed for the webhook-to-CDR direction:
+
+```json
+{
+  "event": "phone_call.dial_finished",
+  "dial_status": "answered",
+  "session": {
+    "id": "5f3e…",
+    "caller_number": "+15551234567",
+    "dialed_number": "+14155550100",
+    "sip_call_id": "7f3a9c@sbc.example.com",
+    "metadata": { "lead_ref": "L-2041" }
+  }
+}
+```
+
 ## Update the configuration
 
 Change any part of an imported number's trunk configuration in place: rotate digest credentials, adjust the allowed addresses, or add, change, and remove the termination. In the console, open **Edit configuration** from the number's row menu; over the API, `PUT` the full desired configuration:
@@ -156,16 +219,18 @@
     "termination_uri": "pbx.example.com",
     "termination_transport": "tls",
     "termination_auth_username": "fish-outbound",
-    "termination_auth_password": ""
+    "termination_auth_password": "",
+    "termination_headers": { "X-Customer-Id": "acme" }
   }'
 ```
 
-The body is the import payload without `phone_number`, `label`, and `agent_id`, and it replaces the whole configuration. Two conveniences:
+The body is the import payload without `phone_number`, `label`, and `agent_id`, and it replaces the whole configuration. Three things to know:
 
 - An empty password next to a set username keeps the stored password, so you can edit other fields without re-entering secrets. Setting a username for the first time requires a password.
 - An empty `termination_uri` removes the termination and makes the number inbound-only again.
+- `termination_headers` replaces the stored map; omit it or send `{}` to remove all custom headers.
 
-Updates apply in place: routing is never interrupted, and calls already in progress are unaffected. The response is the updated number object; for imported numbers it carries the non-secret configuration (`inbound_auth_username`, `inbound_allowed_addresses`, `termination_uri`, `termination_transport`, `termination_auth_username`) alongside `supports_outbound`.
+Updates apply in place: routing is never interrupted, and calls already in progress are unaffected. The response is the updated number object; for imported numbers it carries the non-secret configuration (`inbound_auth_username`, `inbound_allowed_addresses`, `termination_uri`, `termination_transport`, `termination_auth_username`, `termination_headers`) alongside `supports_outbound`.
 
 ## Billing
 

agents/telephony/inbound-calls.mdx

@@ -65,12 +65,13 @@
 
 ## Phone sessions in history
 
-Every answered call becomes a session with `source: "phone"` and two attribution fields:
+Every answered call becomes a session with `source: "phone"` and these attribution fields:
 
 | Field           | Description                                                                 |
 | --------------- | --------------------------------------------------------------------------- |
 | `caller_number` | The caller's number, E.164. `null` for non-phone sessions.                  |
 | `dialed_number` | The workspace number that was called, E.164. `null` for non-phone sessions. |
+| `sip_call_id`   | The SIP `Call-ID` of the carrier's INVITE, for [matching your SIP records](/agents/telephony/byo-sip#match-calls-with-your-sip-records). |
 
 List calls with the standard sessions endpoint. The `caller_number` filter is an exact match; bare numbers are automatically prefixed with `+`, so `15551234567` matches `+15551234567`:
 
@@ -97,8 +98,8 @@
       "metadata": {}
     }
   ],
   "has_more": false,
   "next_cursor": null
 }
 ```