# Events

The `events` array in an Exchange records session activity, tool calls and results, transfers, and errors. Each event has a timestamp and type-specific data.

## Event structure

Each event object includes:

| Field  | Type     | Description                                   |
| ------ | -------- | --------------------------------------------- |
| `type` | `string` | The event type identifier                     |
| `time` | `string` | ISO 8601 timestamp of when the event occurred |
| `data` | `object` | Type-specific event data                      |

## Common event types

| Event Type      | Description                                               |
| --------------- | --------------------------------------------------------- |
| `session_start` | Marks the beginning of the conversation session           |
| `tool_call`     | Records when the Assistant invokes a tool                 |
| `tool_result`   | Records the result returned by a tool                     |
| `session_end`   | Marks the end of the conversation with summary statistics |
| `startup_request` | Records a configured startup HTTP request and its outcome |
| `assistant_transfer` | Records a successful transfer to another Assistant |
| `assistant_transfer_failed` | Records a failed Assistant transfer |
| `amd_result` | Records the answering machine detection result when it runs |

Other events can describe user inactivity, session errors, or audio decoding errors.

***

:::info{title="Note"}

The examples record a technical support call in which the Assistant checked system status. See [Messages](/docs/messages) for the transcript.

:::

***

## session_start

Recorded when the conversation session starts. Its `data` object is empty.

### Example

```json
{
  "type": "session_start",
  "time": "2025-12-15T16:04:46.420863",
  "data": {}
}
```

***

## tool_call

Recorded when the Assistant invokes a tool during the conversation. This event captures the tool name, the arguments passed to it, and whether it's an MCP tool.

For MCP tools, the SDK reports the call and result after execution. Their timestamps can therefore reflect when the execution was recorded rather than its actual start time.

### Data fields

| Field         | Type      | Description                                                    |
| ------------- | --------- | -------------------------------------------------------------- |
| `toolName`   | `string`  | Name of the tool being called                                  |
| `arguments`   | `object` or `string` | Arguments passed to the tool; encoding depends on the tool                |
| `isMcpTool` | `boolean` | Whether this tool is provided via Model Context Protocol (MCP) |

### Example

```json
{
  "type": "tool_call",
  "time": "2025-12-15T16:05:29.074603",
  "data": {
    "toolName": "getSystemStatus",
    "arguments": "{}",
    "isMcpTool": true
  }
}
```

***

## tool_result

Recorded immediately after a tool call completes. This event captures the tool's response and whether an error occurred.

### Data fields

| Field         | Type      | Description                                                   |
| ------------- | --------- | ------------------------------------------------------------- |
| `toolName`   | `string`  | Name of the tool that was called                              |
| `result`      | `any`     | Tool response; it may be structured data or a string                    |
| `hasError`   | `boolean` | Whether the tool execution resulted in an error               |
| `isMcpTool` | `boolean` | Whether this tool is provided via Model Context Protocol (MCP) |

### Example

```json
{
  "type": "tool_result",
  "time": "2025-12-15T16:05:29.074622",
  "data": {
    "toolName": "getSystemStatus",
    "result": "{\"type\":\"text\",\"text\":\"{\\n  \\\"message\\\": \\\"System status: OK\\\"\\n}\",\"annotations\":null,\"meta\":null}",
    "hasError": false,
    "isMcpTool": true
  }
}
```

***

## session_end

Recorded after post-processing at the end of the conversation. Contains summary statistics for the call.

### Data fields

| Field                 | Type     | Description                                                       |
| --------------------- | -------- | ----------------------------------------------------------------- |
| `durationSeconds`    | `number` | Total duration of the conversation in seconds                     |
| `messageCount`       | `object` | Message counts by sender                                          |
| `messageCount.user`  | `number` | Number of messages from the user                                  |
| `messageCount.assistant`   | `number` | Number of messages from the Assistant                             |
| `messageCount.total` | `number` | Total number of messages                                          |
| `eventCount`         | `number` | Total number of events during the session (excluding session_end) |
| `audioUrl`           | `string` or `null` | URL to the conversation audio recording (for voice conversations) |

### Example

```json
{
  "type": "session_end",
  "time": "2025-12-15T16:05:54.882712",
  "data": {
    "durationSeconds": 68,
    "messageCount": {
      "user": 3,
      "assistant": 5,
      "total": 8
    },
    "eventCount": 3,
    "audioUrl": "https://reecall-livekit.s3.eu-west-3.amazonaws.com/281d82f5-a30d-44be-8e66-c35ff2cef718/4111b855-ca91-40f0-897f-93292a09da58/AI%20Technical%20Support_efc242e6-4aab-4cc5-9a7d-ce7fb0cf0188_webrtc_7c09e008-a836-4607-9c59-6336a07368c0.ogg"
  }
}
```

***

## Complete example: technical support conversation

This events array records the session start, a system-status tool call and its result, and the session end.

```json
[
  {
    "type": "session_start",
    "time": "2025-12-15T16:04:46.420863",
    "data": {}
  },
  {
    "type": "tool_call",
    "time": "2025-12-15T16:05:29.074603",
    "data": {
      "toolName": "getSystemStatus",
      "arguments": "{}",
      "isMcpTool": true
    }
  },
  {
    "type": "tool_result",
    "time": "2025-12-15T16:05:29.074622",
    "data": {
      "toolName": "getSystemStatus",
      "result": "{\"type\":\"text\",\"text\":\"{\\n  \\\"message\\\": \\\"System status: OK\\\"\\n}\",\"annotations\":null,\"meta\":null}",
      "hasError": false,
      "isMcpTool": true
    }
  },
  {
    "type": "session_end",
    "time": "2025-12-15T16:05:54.882712",
    "data": {
      "durationSeconds": 68,
      "messageCount": {
        "user": 3,
        "assistant": 5,
        "total": 8
      },
      "eventCount": 3,
      "audioUrl": "https://reecall-livekit.s3.eu-west-3.amazonaws.com/281d82f5-a30d-44be-8e66-c35ff2cef718/4111b855-ca91-40f0-897f-93292a09da58/AI%20Technical%20Support_efc242e6-4aab-4cc5-9a7d-ce7fb0cf0188_webrtc_7c09e008-a836-4607-9c59-6336a07368c0.ogg"
    }
  }
]
```

### Event timeline

| Time     | Event           | Description                                                 |
| -------- | --------------- | ----------------------------------------------------------- |
| 16:04:46 | `session_start` | User connects to the Technical Support Assistant via WebRTC |
| 16:05:29 | `tool_call`     | Assistant invokes `getSystemStatus` to check for outages    |
| 16:05:29 | `tool_result`   | Tool returns "System status: OK"                            |
| 16:05:54 | `session_end`   | Conversation ends after 68 seconds with 8 total messages    |

## Usage notes

* Events are ordered chronologically by their `time` field
* A normally completed session includes `session_start` and `session_end`
* Tool executions normally produce a `tool_call` followed by a `tool_result`; an interrupted execution may leave an unmatched call
* The `eventCount` in `session_end` counts events that occurred during the session (not including `session_end` itself)
* Timestamps use ISO 8601 and may include fractional seconds
* `session_end.data.messageCount` counts the live messages; a post-processed transcript may contain a different number of messages
* If post-processing fails, `session_end.data` can also include `postProcessingFailed` and `postProcessingError`

## What's next

- [Resources](/docs/resources)
- [Messages](/docs/messages)
