diff --git a/agents/monitor/conversation-history.mdx b/agents/monitor/conversation-history.mdx index 7b2a955..945a251 100644 --- a/agents/monitor/conversation-history.mdx +++ b/agents/monitor/conversation-history.mdx @@ -76,7 +76,7 @@ Each row carries the session facts: ### 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. +`status` says whether a conversation happened: `completed` means the caller and an agent were both on the call and it is over (it is billed even if the runtime ended it), `failed` means no conversation took place (nobody connected, or the caller connected and no agent ever joined), `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. On a `failed` session where the caller did connect, `started_at`, `ended_at` and `duration_seconds` describe how long they waited; nothing is billed. `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. @@ -87,8 +87,8 @@ Each row carries the session facts: | `escalated` | `completed` | The call was transferred to a human. See [Transfer items](#transfer-items) | | `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 | +| `agent_join_timeout` | `failed` | The caller connected but no agent joined the call | +| `internal_error` | `completed` | The agent runtime hit an internal error (`failed` when it failed before the conversation started) | | `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 | diff --git a/agents/monitor/webhooks.mdx b/agents/monitor/webhooks.mdx index 0b2a7cb..047c231 100644 --- a/agents/monitor/webhooks.mdx +++ b/agents/monitor/webhooks.mdx @@ -185,7 +185,7 @@ Every payload carries the `event` name and a `session` object with the session f -`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. +`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. A caller who connected and waited for an agent that never joined does produce `call.ended`, with `session.status` set to `failed` and `ended_reason` set to `agent_join_timeout`. 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`.