docs(agents): session id in webhook tools, call_sid on session reads

agents/build/dynamic-variables.mdx

@@ -33,7 +33,7 @@
 and they are on the {{plan}} plan. Greet them by name.
 ```
 
 Pass values as a flat object of strings, numbers, or booleans. Variable names must match `[A-Za-z][A-Za-z0-9_]*` (no hyphens or dots; the dotted `system.*` names are reserved for [system variables](#system-variables)), string values are capped at 100,000 characters, and a request can carry at most 500 variables totaling 1 MiB as UTF-8 JSON. Violations reject session creation with `422`:
 
 <CodeGroup>
 ```bash API (curl)
@@ -121,7 +121,7 @@
 ```
 
 <Tip>
 In `agentId` mode, values arrive from the end user's browser. Treat them as untrusted input, and use `sessionToken` mode when personalization must come from data only your backend knows.
 </Tip>
 
 ### Custom variables in webhook tools
@@ -132,28 +132,28 @@
 https://ehr.example.com/patients/{{patient_id}}/appointments?clinic={{clinic_id}}
 ```
 
 - In the URL the value is URL-encoded, like argument values. In header values and the body template it is inserted as is. Numbers render as written, booleans as `true` or `false`.
 - When the tool declares an argument with the same name as a custom variable, the argument wins: that placeholder is filled from what the agent supplies.
 - A placeholder with no value renders as an empty string in the request, unlike in the prompt, where it stays visible.
 
 <Warning>
 On a [public agent](/agents/deploy/public-agents) the browser supplies custom values, so anyone can start a session with any `patient_id`. When a templated value identifies a person, don't let it authorize access to their data on its own: create sessions from your backend (`sessionToken` mode), or let the inbound call webhook supply it on phone calls.
 </Warning>
 
 ## System variables
 
 The platform fills a handful of `{{system.*}}` placeholders itself, on every session. You cannot supply or override them: the names you pass in `dynamic_variables` cannot contain a dot, so the two namespaces never collide.
 
 | Variable | Value | Notes |
 |---|---|---|
 | `system.channel` | `phone_inbound`, `phone_outbound`, or `web_voice` | Web SDK, API, preview, and Single Turn and Tool test sessions are `web_voice`. A Simulation test uses its [channel](/agents/test/agent-tests#channel). |
 | `system.timezone` | The session's resolved IANA timezone, for example `Asia/Tokyo` | `UTC` when nothing resolves. Always equals the session's `timezone` field; see [which timezone a session uses](/agents/build/time-timezone#which-timezone-a-session-uses). |
 | `system.today` | Today's date in that timezone, ISO 8601 `YYYY-MM-DD` | The calendar date at session creation. There is no `system.now`; see [World context](#world-context). |
-| `system.language` | The session language code, one of the [52 supported languages](/agents/build/voice-language#speaking-language) |
- The `language` [override](/agents/deploy/authenticated-sessions#overrides) when the request carries one, otherwise the agent's [speaking language](/agents/build/voice-language#speaking-language). |
+| `system.language` | The session language code, one of the [52 supported languages](/agents/build/voice-language#speaking-language) | The `language` [override](/agents/deploy/authenticated-sessions#overrides) when the request carries one, otherwise the agent's [speaking language](/agents/build/voice-language#speaking-language). |
 | `system.caller_number` | The human party's number, E.164 | Inbound: the caller (empty if withheld or not a valid E.164 number). Outbound: the number you dialed. Empty on non-phone sessions. |
 | `system.caller_number_spoken` | The same number written for speech, for example `+1; 4 1 5; 5 5 5; 0 1 2 3` | Use it wherever the agent should say the number out loud; see [Reading a number out loud](#reading-a-number-out-loud). Empty whenever `system.caller_number` is empty. |
 | `system.dialed_number` | Your workspace number, E.164 | Inbound: the number that was called. Outbound: the number the call was placed from. Empty on non-phone sessions. |
+| `system.session_id` | The session's id, for example `sess_5f3e…` | Send it from a [webhook tool](#in-webhook-tools) to tie each tool call to its session. Outside the agent, the same id is in the `POST /v1/agent/sessions` [response](/agents/deploy/authenticated-sessions), the SDK's `connect` event, and `session.id` in [post-call webhooks](/agents/monitor/webhooks), and [`GET /v1/agent/sessions/{session_id}`](/agents/monitor/conversation-history#get-a-session) accepts it. |
 
 ### Reading a number out loud
 
@@ -197,13 +197,9 @@
 
 A reference to a system variable that does not exist (`{{system.foo}}`) is rejected with `422` when you save the configuration or the tool, and when you send it in session overrides. The error lists the available names.
 
-<Note>
-There is no `system.session_id`. The configuration is rendered before the session receives its id, so the id cannot be templated into it. Read it from the `POST /v1/agent/sessions` [response](/agents/deploy/authenticated-sessions), the SDK's `connect` event, or the `session` object in [webhooks](/agents/monitor/webhooks).
-</Note>
-
 ## World context
 
 The agent knows the current date and time without any variable. The platform states the date and the session's timezone at the start of every session and refreshes the time on every turn, so "tomorrow morning" or "next Tuesday" resolve correctly even in a long conversation. You don't need a custom `{{today}}` or `{{now}}`, and there is no `system.now`: variables render once, when the session is created, so a templated time would be stale from the first reply onward. When you want the date or timezone as text in a template, for example in a webhook tool URL, use the [`system.today` and `system.timezone`](#system-variables) system variables.
 
 See [Time & timezone](/agents/build/time-timezone) for how the timezone is resolved and how to turn the injection off for a session (`world_context: false`).
 

agents/build/webhook-tools.mdx

@@ -37,7 +37,7 @@
 
 ## Argument templating
 
-Reference any declared argument with `{{name}}`: in the URL, in header values, or in the body template. The platform substitutes the values the agent supplies before sending the request. [Dynamic variables](/agents/build/dynamic-variables#custom-variables-in-webhook-tools) work in the same places: your custom variables, such as a customer id returned by the inbound call webhook, and system variables such as `{{system.caller_number}}` or `{{system.today}}`. They are filled when the session starts, before the agent supplies any argument. An argument wins over a custom variable of the same name.
+Reference any declared argument with `{{name}}`: in the URL, in header values, or in the body template. The platform substitutes the values the agent supplies before sending the request. [Dynamic variables](/agents/build/dynamic-variables#custom-variables-in-webhook-tools) work in the same places: your custom variables, such as a customer id returned by the inbound call webhook, and system variables such as `{{system.session_id}}`, `{{system.caller_number}}` or `{{system.today}}`. They are filled when the session starts, before the agent supplies any argument. An argument wins over a custom variable of the same name.
 
 ```text Endpoint URL
 https://api.example.com/orders/{{order_number}}
@@ -166,7 +166,7 @@
 { "ticket_id": "T-1042", "expected_reply": "within 24 hours" }
 ```
 
 Ticket numbers get spoken aloud: short, pronounceable IDs survive text-to-speech far better than UUIDs.
 
 <Note>
   An in-call ticket depends on the model choosing to escalate. For a safety net

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
 
@@ -60,18 +60,19 @@
       "caller_number": "+15551234567",
       "dialed_number": "+14155550100",
       "sip_call_id": "7f3a9c@sbc.example.com",
+      "call_sid": "CA5d3a…",
       "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. `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), `end_user_id` is the end-user identifier you passed (`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). `call_sid` is the carrier's id of the call: Twilio's CallSid on an inbound call through a Twilio number, the same value the [inbound call webhook](/agents/monitor/webhooks#inbound-call-webhook) sends. It is `null` on other sessions. `name` is the display name you passed when creating the session (`null` when omitted), `end_user_id` is the end-user identifier you passed (`null` when omitted), and `metadata` echoes back whatever you attached when creating the session.
 
 ### Status and end reason
 
@@ -105,6 +106,7 @@
 | `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              |
 | `end_user_id`                      | Exact, case-sensitive match on the `end_user_id` you set when [creating the session](/agents/deploy/authenticated-sessions), for listing one customer's sessions |
+| `call_sid`                         | Exact match on `call_sid`, for looking up the session behind an [inbound call webhook](/agents/monitor/webhooks#inbound-call-webhook) request |
 | `created_after` / `created_before` | ISO 8601 timestamps                                                                                   |
 
 <Note>
@@ -194,7 +196,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

@@ -92,7 +92,7 @@
 
 ## Payload
 
-Every payload carries the `event` name and a `session` object with a fixed set of session facts. Note the field names differ from the [sessions API](/agents/monitor/conversation-history), which uses `session_id` / `started_at` / `ended_at` for the same facts. `call.ended` adds `ended_reason`; `call.analyzed` adds the `analysis` entity; `phone_call.dial_finished` adds top-level `dial_status` and `answered_by`:
+Every payload carries the `event` name and a `session` object with the session facts. Note the field names differ from the [sessions API](/agents/monitor/conversation-history), which uses `session_id` / `started_at` / `ended_at` for the same facts. `call.ended` adds `ended_reason`; `call.analyzed` adds the `analysis` entity; `phone_call.dial_finished` adds top-level `dial_status` and `answered_by`. The `session` object is the same on every event. The `phone_call.dial_finished` example shows it in full, the others are shortened.
 
 <CodeGroup>
 
@@ -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"
 }
 ```
 
@@ -170,6 +170,7 @@
     "caller_number": "+15551234567",
     "dialed_number": "+14155550100",
     "sip_call_id": "7f3a9c@sbc.example.com",
+    "call_sid": "",
     "batch_call_id": null,
     "conversation_started_at": "2026-07-23T12:01:12Z",
     "conversation_ended_at": null,
@@ -190,6 +191,8 @@
 
 `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).
 
+`call_sid` is the carrier's id of the call. Today that is Twilio's CallSid on an inbound call through a Twilio number. It is the same value the [inbound call webhook](#inbound-call-webhook) request carries, so you can join that request to the session. It is an empty string on web sessions, outbound calls, and calls through your own SIP trunk.
+
 `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.
@@ -280,14 +283,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
@@ -295,6 +298,16 @@
   published agent.
 </Note>
 
+### Forward compatibility
+
+Payloads change additively. This applies to every webhook on this page, including the [inbound call webhook](#inbound-call-webhook) request.
+
+- New fields can appear at any time, at the top level and inside `session`, `analysis` and `call`. They come without a new event name.
+- Published fields never change name, type or meaning, and are never removed.
+- Enum fields such as `status` and `ended_reason` can gain new values.
+
+Parse payloads without rejecting unknown fields. A receiver that validates against a strict schema breaks when a field is added. Treat an enum value you don't recognize as a generic case instead of failing.
+
 ## Inbound call webhook
 
 `webhooks.conversation_init` is a single endpoint called while an [inbound phone call](/agents/telephony/inbound-calls) is being set up, before the agent answers. It receives the caller's number and returns `dynamic_variables` that fill the `{{placeholders}}` in the agent's published prompt and first message, so the agent can greet a known customer by name or pick up an open order. In the console it is the **Inbound call webhook** on the agent's Webhooks page.
@@ -336,16 +349,18 @@
     "dialed_number": "+14155550100",
     "agent_id": "a1b2…",
     "phone_number_id": "7e9f…",
-    "twilio_call_sid": "CA5d3a…"
+    "call_sid": "CA5d3a…"
   }
 }
 ```
 
-`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.
+`caller_number` and `dialed_number` are E.164. `caller_number` is an empty string when the carrier withholds the caller's number, and `call_sid` is empty when the call did not come through a Twilio number.
+
+To match this request with the call, keep `call_sid`. Once the call is connected, `GET /v1/agent/sessions?call_sid=…` returns its session, and post-call webhooks carry the same value. This works only when `call_sid` is not empty, that is for calls through a Twilio number. During the call, webhook tools can send the session id with `{{system.session_id}}`. New fields can be added to this request, see [Forward compatibility](#forward-compatibility).
 
 ### 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 100,000 characters), numbers, or booleans, and at most 500 entries totaling 1 MiB are read.
 
 ```json Response
 {
@@ -377,7 +392,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:
 
@@ -498,11 +513,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/inbound-calls.mdx

@@ -72,6 +72,7 @@
 | `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). |
+| `call_sid`      | Twilio's CallSid on a call through a Twilio number, the same value the [inbound call webhook](/agents/monitor/webhooks#inbound-call-webhook) sends. `null` on other calls. |
 
 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`:
 
@@ -98,8 +99,8 @@
       "metadata": {}
     }
   ],
   "has_more": false,
   "next_cursor": null
 }
 ```