fishaudio · Him188 · Sep 19, 2026 · Sep 18, 2026 · coderabbitai · Sep 18, 2026
diff --git a/agents/build/custom-llm.mdx b/agents/build/custom-llm.mdx
@@ -58,16 +58,16 @@
        "parameters": {
          "type": "object",
          "properties": {
            "order_number": { "type": "string", "description": "The order number, e.g. A12345." }
          },
          "required": ["order_number"]
        }
      }
    }
  ],
  "session_id": "sess_01j9x4k2m8v3q7n5p6r8t9w0y1",
  "user_id": "user-42",
  "fishaudio_extra_body": { "chat_id": "chat-9" }
 }
 ```

@@ -126,7 +126,7 @@
 
 - Each request gets one retry and a 10 second response cap.
 - When a generation still fails, the agent speaks a brief hold line and stays on the call.
-- After three consecutive failed generations the agent apologizes, hangs up, and the session records `ended_reason: llm_endpoint_failure`. Each failure also emits an `llm.endpoint_error` event on the session timeline.
+- After three consecutive failed generations the agent apologizes, hangs up, and the session ends with `end_reason: llm_endpoint_failure` (in the [sessions API](/agents/monitor/conversation-history#status-and-end-reason), the dashboard, and the `call.ended` webhook's `ended_reason`). Each failure also emits an `llm.endpoint_error` event on the session timeline.
 
 <Tip>
 Voice conversations are latency sensitive, so aim for a time-to-first-token under 800 ms. Turn latency is attributed per session in [conversation history](/agents/monitor/conversation-history), which lets you tell endpoint time from platform time.

diff --git a/agents/monitor/conversation-history.mdx b/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

@@ -54,6 +54,7 @@
       "agent_name": "Support agent",
       "name": "Order #4821 follow-up",
       "status": "completed",
+      "end_reason": "user_hangup",
       "source": "phone",
       "caller_number": "+15551234567",
       "dialed_number": "+14155550100",
@@ -63,19 +64,42 @@
      "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.
 
+### Status and end reason
+
+`status` says whether a conversation happened: `completed` means a participant connected and the call is over (it is billed even if the runtime ended it), `failed` means nobody ever connected, `active` means it is in progress, `pending` means the session was created and no one has connected yet, and `unknown` means the platform temporarily lost track of a live call.
+
+`end_reason` says why it ended. It is `null` while a session is live, for a short moment after it ends, and on sessions that predate the field.
+
+| `end_reason`           | `status`    | Meaning                                                                          |
+| ---------------------- | ----------- | -------------------------------------------------------------------------------- |
+| `user_hangup`          | `completed` | The caller hung up                                                               |
+| `agent_hangup`         | `completed` | The agent ended the call (end-call tool, workflow end node, or idle hangup)      |
+| `escalated`            | `completed` | The call was transferred to a human                                              |
+| `conversation_timeout` | `completed` | The call reached its maximum duration                                            |
+| `heartbeat_timeout`    | `completed` | The agent runtime stopped responding mid-call                                    |
+| `agent_join_timeout`   | `completed` | The caller connected but no agent joined the call                                |
+| `internal_error`       | `completed` | The agent runtime hit an internal error                                          |
+| `llm_endpoint_failure` | `completed` | A [custom LLM](/agents/build/custom-llm) failed repeatedly and the agent hung up |
+| `room_join_timeout`    | `failed`    | The caller never connected before the join deadline                              |
+| `cancelled`            | `failed`    | The session was ended before anyone connected                                    |
+| `dial_failed`          | `failed`    | An outbound call was not answered; `dial_status` has the detail                  |
+
+The same values appear on the [`call.ended` webhook](/agents/monitor/webhooks) and in the dashboard, so the three surfaces never disagree about a session.
+
 ### Filters
 
 | Parameter                          | Behavior                                                                                              |
 | ---------------------------------- | ----------------------------------------------------------------------------------------------------- |
 | `agent_id`                         | Sessions of a single agent                                                                            |
 | `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              |
 | `created_after` / `created_before` | ISO 8601 timestamps                                                                                   |
 
@@ -109,6 +133,7 @@
 {
   "session_id": "…",
   "status": "completed",
+  "end_reason": "user_hangup",
   "items": [
     {
       "type": "message",
@@ -164,7 +189,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`.

diff --git a/agents/monitor/webhooks.mdx b/agents/monitor/webhooks.mdx
@@ -105,15 +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": "hangup"
+  "ended_reason": "user_hangup"
 }
 ```
 
@@ -180,7 +181,7 @@
 
 </CodeGroup>
 
-`ended_reason` is `hangup` for a call that terminated normally and `error` when the session failed. New values may be added as richer end causes ship. Treat unrecognized values as informational rather than rejecting the event.
+`ended_reason` is the same value as `session.end_reason` and uses the [sessions API vocabulary](/agents/monitor/conversation-history#status-and-end-reason): `user_hangup`, `agent_hangup`, `escalated`, `conversation_timeout`, `heartbeat_timeout`, `agent_join_timeout`, `internal_error`, or `llm_endpoint_failure`. `call.ended` is only sent for sessions in which a participant connected, so the never-connected reasons (`room_join_timeout`, `cancelled`, `dial_failed`) do not appear here; query the sessions API with `status=failed` for those. In the rare case the reason is not settled yet at delivery time, both fields are `null`. New values may be added; treat unrecognized values as informational rather than rejecting the event.
 
 `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`.
 
@@ -274,14 +275,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
@@ -335,11 +336,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
 {
@@ -371,7 +372,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:

@@ -492,11 +493,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.