# Notification event types (/en/ai/reference/event-types)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

After enabling Agora message notifications, the Agora notification server sends channel event notifications to your server through HTTPS POST requests. The data format is `JSON`, the character encoding is `UTF-8`, and the signature algorithm can be either `HMAC/SHA1` or `HMAC/SHA256`.

This page explains the types of events returned in channel event callbacks and their meanings.

If you are starting from a product goal instead of an event number, begin with [Monitor agent status, errors, and performance](../build/handle-runtime-events/monitor-agent-runtime).

For webhook setup, request format, and signature verification, see [Webhooks](../build/handle-runtime-events/webhooks).

## Choose event types by goal [#choose-event-types-by-goal]

| Goal                                                | Use these event types                                                                                      | What they help you answer                                                                                                                                                    |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Confirm that a session started or ended             | [`101 agent joined`](#101-agent-joined), [`102 agent left`](#102-agent-left)                               | Did the agent enter the channel? How did the session end?                                                                                                                    |
| Retrieve conversation history after a session       | [`103 agent history`](#103-agent-history)                                                                  | What was said during the session? See [Retrieve conversation history after a session ends](../build/handle-runtime-events/retrieve-session-history).                         |
| Investigate failures and alert on production issues | [`110 agent error`](#110-agent-error), [`102 agent left`](#102-agent-left)                                 | Which module failed? Did the session terminate because of that failure? See [Debug agent failures with runtime events](../build/handle-runtime-events/debug-agent-failures). |
| Measure latency and runtime health                  | [`111 agent metrics`](#111-agent-metrics)                                                                  | How long do LLM and TTS stages take? Are there regressions?                                                                                                                  |
| Track telephony call progress                       | [`201 inbound call state`](#201-inbound-call-state), [`202 outbound call state`](#202-outbound-call-state) | Where is the SIP call in its lifecycle?                                                                                                                                      |

## Request header [#request-header]

The message notification callback header contains the following fields:

<ParameterList title="Header">
  <Parameter name="Content-Type" type="string">
    Application/json
  </Parameter>

  <Parameter name="Agora-Signature" type="string">
    The signature value generated by Agora using the customer key and `HMAC/SHA1` algorithm. Use the customer key and `HMAC/SHA1` algorithm to verify the signature value. See Verify the signature for details.
  </Parameter>

  <Parameter name="Agora-Signature-V2" type="string">
    The signature value generated by Agora using the customer key and `HMAC/SHA256` algorithm. Use the customer key and `HMAC/SHA256` algorithm to verify the signature value. See Verify the signature for details.
  </Parameter>
</ParameterList>

## Request body [#request-body]

The message notification callback request body contains the following fields:

<ParameterList>
  <Parameter name="noticeId" type="string">
    Notification ID. Identifies an event notification from the Agora server.
  </Parameter>

  <Parameter name="productId" type="integer">
    Business ID. A value of `17` indicates a Conversational AI Engine notification.
  </Parameter>

  <Parameter name="eventType" type="integer">
    The event type of the notification. See [Event types](#event-types) for details.
  </Parameter>

  <Parameter name="notifyMs" type="integer">
    The Unix timestamp (ms) indicating when the Agora message server sent the event notification to your server. This value is updated when the notification is retried.
  </Parameter>

  <Parameter name="sid" type="string">
    The session ID.
  </Parameter>

  <Parameter name="payload" type="object">
    The specific content of the notification event. `payload` varies depending on the event type. For details, see [Event types](#event-types).
  </Parameter>
</ParameterList>

Following is an example of a message notification callback request body:

```json
{
  "sid": "C866467GVJJ54687",
  "noticeId": "2000001428:4330:107",
  "productId": 17,
  "eventType": 101,
  "notifyMs": 1611566412672,
  "payload": {}
}
```

## Event types [#event-types]

The Agora message notification service notifies the following Conversational AI Engine events:

| Event Type                      | Event name          | Event description                                                                                                                                                                                                                                                                                                                               |
| :------------------------------ | :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [101](#101-agent-joined)        | agent joined        | The agent joins the channel.                                                                                                                                                                                                                                                                                                                    |
| [102](#102-agent-left)          | agent left          | The agent leaves the channel.                                                                                                                                                                                                                                                                                                                   |
| [103](#103-agent-history)       | agent history       | After an agent stops, this event notifies the stored history, which includes messages exchanged between the user and the agent and timestamps indicating when the agent was created and stopped. The maximum number of entries is determined by the `llm.max_history` parameter you can set when starting the agent. The default value is `32`. |
| [104](#104-agent-expire)        | agent expire        | The agent's RTC token is about to expire.                                                                                                                                                                                                                                                                                                       |
| [110](#110-agent-error)         | agent error         | Agent error.                                                                                                                                                                                                                                                                                                                                    |
| [111](#111-agent-metrics)       | agent metrics       | The performance metrics of an agent.                                                                                                                                                                                                                                                                                                            |
| [112](#112-turns-finished)      | turns finished      | Batch callback of dialogue round data after the session ends.                                                                                                                                                                                                                                                                                   |
| [201](#201-inbound-call-state)  | inbound call state  | Changes in the status of an incoming call.                                                                                                                                                                                                                                                                                                      |
| [202](#202-outbound-call-state) | outbound call state | Changes in the status of an outgoing call.                                                                                                                                                                                                                                                                                                      |

### 101 agent joined [#101-agent-joined]

An `eventType` of `101` indicates that an agent has joined a channel. The `payload` contains the following fields:

<ParameterList title="payload">
  <Parameter name="agent_id" type="string">
    Unique identifier of the agent.
  </Parameter>

  <Parameter name="name" type="string">
    The agent name provided when calling [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join). Unique within a channel.
  </Parameter>

  <Parameter name="start_ts" type="integer">
    Timestamp indicating when the agent was created.
  </Parameter>

  <Parameter name="channel" type="string">
    The name of the channel the agent was in.
  </Parameter>

  <Parameter name="labels" type="object" required="false">
    Custom labels in key-value pair format. Contains the same labels that were set when starting the agent.
  </Parameter>
</ParameterList>

#### Payload example [#payload-example]

```json
{
  "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
  "name": "my-agent",
  "start_ts": 1737111452,
  "channel": "xxxxx",
  "labels": {
    "campaign_id": "test_campaign",
    "customer_group": "vip"
  }
}
```

### 102 agent left [#102-agent-left]

An `eventType` of `102` indicates that an agent has left a channel. The `payload` contains the following fields:

<ParameterList title="payload">
  <Parameter name="agent_id" type="string">
    Unique identifier of the agent.
  </Parameter>

  <Parameter name="name" type="string">
    The agent name provided when calling [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join). Unique within a channel.
  </Parameter>

  <Parameter name="start_ts" type="integer">
    Timestamp indicating when the agent was created.
  </Parameter>

  <Parameter name="stop_ts" type="integer">
    Timestamp indicating when the agent left the channel.
  </Parameter>

  <Parameter name="channel" type="string">
    The name of the channel the agent was in.
  </Parameter>

  <Parameter name="status" type="string">
    Agent status.
  </Parameter>

  <Parameter name="message" type="string">
    The reason why the agent left the channel.
  </Parameter>

  <Parameter name="labels" type="object" required="false">
    Custom labels in key-value pair format. Contains the same labels that were set when starting the agent.
  </Parameter>
</ParameterList>

#### Payload examples [#payload-examples]

Following are some examples of the `payload` when an agent leaves a channel for different reasons.

<Tabs>
  <TabsList>
    <TabsTrigger value="manual">
      Agent manually stopped
    </TabsTrigger>

    <TabsTrigger value="idle-timeout">
      Agent idle timeout
    </TabsTrigger>

    <TabsTrigger value="agent-error">
      Agent error
    </TabsTrigger>

    <TabsTrigger value="rtc-connection">
      RTC connection error
    </TabsTrigger>

    <TabsTrigger value="task-lifetime">
      Task lifetime limit exceeded
    </TabsTrigger>
  </TabsList>

  <TabsContent value="manual">
    ```json
    {
       "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
       "name": "my-agent",
       "start_ts": 1737111452,
       "stop_ts": 1737111455,
       "channel": "xxxxx",
       "status": "STOPPED",
       "message": "OK",
       "labels": {
         "campaign_id": "test_campaign",
         "customer_group": "vip"
       }
    }
    ```
  </TabsContent>

  <TabsContent value="idle-timeout">
    ```json
    {
       "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
       "name": "my-agent",
       "start_ts": 1737111452,
       "stop_ts": 1737111455,
       "channel": "xxxxx",
       "status": "STOPPED",
       "message": "Idle for too long",
       "labels": {
         "campaign_id": "test_campaign",
         "customer_group": "vip"
       }
    }
    ```
  </TabsContent>

  <TabsContent value="agent-error">
    ```json
    {
       "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
       "name": "my-agent",
       "start_ts": 1737111452,
       "stop_ts": 1737111455,
       "channel": "xxxxx",
       "status": "FAILED",
       "message": "Connecting for too long",
       "labels": {
         "campaign_id": "test_campaign",
         "customer_group": "vip"
       }
    }
    ```
  </TabsContent>

  <TabsContent value="rtc-connection">
    ```json
    {
       "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
       "name": "my-agent",
       "start_ts": 1737111452,
       "stop_ts": 1737111455,
       "channel": "xxxxx",
       "status": "FAILED",
       "message": "RTC connection error",
       "labels": {
         "campaign_id": "test_campaign",
         "customer_group": "vip"
       }
    }
    ```
  </TabsContent>

  <TabsContent value="task-lifetime">
    ```json
    {
       "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
       "name": "my-agent",
       "start_ts": 1737111452,
       "stop_ts": 1737111455,
       "channel": "xxxxx",
       "status": "STOPPED",
       "message": "Task lifetime limit exceeded",
       "labels": {
         "campaign_id": "test_campaign",
         "customer_group": "vip"
       }
    }
    ```
  </TabsContent>
</Tabs>

### 103 agent history [#103-agent-history]

An `eventType` of `103` notifies the history of a user and agent dialogue. The notification `payload` contains the following fields:

<ParameterList title="payload">
  <Parameter name="agent_id" type="string">
    Unique identifier of the agent.
  </Parameter>

  <Parameter name="name" type="string">
    The agent name provided when calling [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join). Unique within a channel.
  </Parameter>

  <Parameter name="channel" type="string">
    The name of the channel the agent was in.
  </Parameter>

  <Parameter name="start_ts" type="integer">
    The timestamp indicating when the agent started and joined the channel.
  </Parameter>

  <Parameter name="stop_ts" type="integer">
    The timestamp indicating when the agent stopped and left the channel.
  </Parameter>

  <Parameter name="contents" type="array">
    Agent history.

    <Parameter name="role" type="string">
      The message sender.

      * `user`: User
      * `assistant`: AI agent
    </Parameter>

    <Parameter name="content" type="string">
      Message content.
    </Parameter>

    <Parameter name="speech_start_ms" type="integer" required="false">
      Unix timestamp in milliseconds indicating when the user started speaking or the agent started TTS playback. Only returned when `llm.vendor` is `custom`.
    </Parameter>

    <Parameter name="speech_end_ms" type="integer" required="false">
      Unix timestamp in milliseconds indicating when the user stopped speaking, or when TTS playback completed or was interrupted. Only returned when `llm.vendor` is `custom`.
    </Parameter>

    <Parameter name="speech_algorithmic_delay" type="integer" required="false">
      The total delay in milliseconds introduced by audio processing algorithms, including noise reduction, background voice suppression, and voiceprint locking, after audio is captured from the user's microphone. Use this value to align timestamps with cloud recording audio.

      Only returned when:

      * `llm.vendor` is `custom`
      * `contents[].role` is `user`
      * Actual voice input is present
    </Parameter>
  </Parameter>

  <Parameter name="labels" type="object" required="false">
    Custom labels in key-value pair format. Contains the same labels that were set when starting the agent.
  </Parameter>
</ParameterList>

<CalloutContainer type="info">
  <CalloutDescription>
    `speech_start_ms`, `speech_end_ms`, and `speech_algorithmic_delay` are returned only in `103 agent history` events for sessions that use `llm.vendor` set to `custom`.
  </CalloutDescription>
</CalloutContainer>

#### Payload examples [#payload-examples-1]

<Tabs>
  <TabsList>
    <TabsTrigger value="basic">
      Basic
    </TabsTrigger>

    <TabsTrigger value="custom-llm">
      Custom LLM
    </TabsTrigger>
  </TabsList>

  <TabsContent value="basic">
    ```json
    {
      "agent_id": "xxxx",
      "name": "my-agent",
      "channel": "xxxx",
      "start_ts": 123,
      "stop_ts": 123,
      "contents": [
        {
          "role": "user",
          "content": "hello."
        },
        {
          "role": "assistant",
          "content": "hi, how can I help you?"
        }
      ],
      "labels": {
        "campaign_id": "test_campaign",
        "customer_group": "vip"
      }
    }
    ```
  </TabsContent>

  <TabsContent value="custom-llm">
    ```json
    {
      "agent_id": "xxxx",
      "name": "my-agent",
      "channel": "xxxx",
      "start_ts": 123,
      "stop_ts": 123,
      "contents": [
        {
          "role": "user",
          "content": "Hello, I need help with my recent order.",
          "speech_start_ms": 1715000001200,
          "speech_end_ms": 1715000003400,
          "speech_algorithmic_delay": 120
        },
        {
          "role": "assistant",
          "content": "Sure, could you please provide your order number?",
          "speech_start_ms": 1715000004100,
          "speech_end_ms": 1715000005000
        },
        {
          "role": "user",
          "content": "I'd like to check the status of my package, tracking number 12345.",
          "speech_start_ms": 1715000005200,
          "speech_end_ms": 1715000007600,
          "speech_algorithmic_delay": 120
        },
        {
          "role": "assistant",
          "content": "Your package with tracking number 12345 is currently out for delivery.",
          "speech_start_ms": 1715000009500,
          "speech_end_ms": 1715000013200
        },
        {
          "role": "user",
          "content": "[think API injected] User level: VIP"
        }
      ],
      "labels": {
        "campaign_id": "test_campaign",
        "customer_group": "vip"
      }
    }
    ```
  </TabsContent>
</Tabs>

### 104 agent expire [#104-agent-expire]

An `eventType` of `104` indicates that the agent's RTC token is about to expire. The `payload` contains the following fields:

<ParameterList title="payload">
  <Parameter name="agent_id" type="string">
    Unique identifier of the agent.
  </Parameter>

  <Parameter name="name" type="string">
    The agent name provided when calling [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join). Unique within a channel.
  </Parameter>

  <Parameter name="start_ts" type="integer">
    Timestamp indicating when the agent was created.
  </Parameter>

  <Parameter name="channel" type="string">
    The name of the channel the agent is in.
  </Parameter>

  <Parameter name="message" type="string">
    Token expiry warning message. Fixed value: `Task exceeded maximum lifetime`.
  </Parameter>
</ParameterList>

<CalloutContainer type="info">
  <CalloutTitle>
    Info
  </CalloutTitle>

  <CalloutDescription>
    This event is a warning only. The agent does not exit the channel or interrupt the session when this event is triggered. Upon receiving this event, call the [Update agent](/en/api-reference/api-ref/conversational-ai/update) API with a new `properties.token` to refresh the token before it expires.
  </CalloutDescription>
</CalloutContainer>

#### Payload example [#payload-example-1]

```json
{
  "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
  "name": "my-agent",
  "start_ts": 1737111452,
  "channel": "xxxxx",
  "message": "Task exceeded maximum lifetime"
}
```

### 110 agent error [#110-agent-error]

An `eventType` of `110` indicates that an agent has encountered an error. The `payload` contains the following fields:

<ParameterList title="payload">
  <Parameter name="agent_id" type="string">
    Unique identifier of the agent.
  </Parameter>

  <Parameter name="name" type="string">
    The agent name provided when calling [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join). Unique within a channel.
  </Parameter>

  <Parameter name="start_ts" type="integer">
    Timestamp indicating when the agent was created.
  </Parameter>

  <Parameter name="channel" type="string">
    The name of the channel the agent was in.
  </Parameter>

  <Parameter name="turn_id" type="string">
    Transcript conversation turn. For details, see [Display live transcripts](../build/transcripts#reference).
  </Parameter>

  <Parameter name="errors" type="array">
    An array of error messages. Each object contains the following fields:

    <Parameter name="module" type="string">
      The module where the error occurred.
    </Parameter>

    <Parameter name="turn_id" type="integer">
      Transcript dialogue turn.
    </Parameter>

    <Parameter name="code" type="integer">
      Error code. Refer to the error code document of the vendor corresponding to the error module for detailed information.
    </Parameter>

    <Parameter name="message" type="string">
      The error message.
    </Parameter>
  </Parameter>

  <Parameter name="labels" type="object" required="false">
    Custom labels in key-value pair format. Contains the same labels that were set when starting the agent.
  </Parameter>
</ParameterList>

#### Payload examples [#payload-examples-2]

<Tabs>
  <TabsList>
    <TabsTrigger value="llm">
      LLM module error
    </TabsTrigger>

    <TabsTrigger value="greeting">
      Greeting audio URL error
    </TabsTrigger>

    {/* <TabsTrigger value="sip">SIP module error</TabsTrigger> */}
  </TabsList>

  <TabsContent value="llm">
    ```json
    {
      "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
      "name": "my-agent",
      "start_ts": 1737111452,
      "channel": "xxxxx",
      "turn_id": 2,
      "errors": [{"module": "llm", "turn_id":2, "code":503, "message": "Insufficient balance."}],
      "labels": {
        "campaign_id": "test_campaign",
        "customer_group": "vip"
      }
    }
    ```
  </TabsContent>

  <TabsContent value="greeting">
    When the greeting audio file fails to download, times out, is in an unsupported format, or fails to decode, the system reports the error via a `110 agent error` event and automatically falls back to TTS synthesis using `greeting_message`. In these errors, `errors[].module` is `agent`.

    ```json
    {
      "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
      "name": "outbound_voice_agent",
      "start_ts": 1737111452,
      "channel": "outbound_call_channel_001",
      "turn_id": 0,
      "errors": [
        {
          "module": "agent",
          "turn_id": 0,
          "code": 4001,
          "message": "Greeting audio URL unreachable, fallback to TTS. audio_url: https://cdn.example.com/audio/welcome.mp3"
        }
      ],
      "labels": {}
    }
    ```
  </TabsContent>

  {/*
    <TabsContent value="sip">

    ```json
    {
    "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
    "name": "my-agent",
    "start_ts": 1737111452,
    "channel": "xxxxx",
    "turn_id": "",
    "errors": [{"module": "sip", "turn_id": "", "code":50, "message": "Insufficient balance."}],
    "labels": {
      "campaign_id": "test_campaign",
      "customer_group": "vip"
    }
    }
    ```
    </TabsContent>
    */}
</Tabs>

<CalloutContainer type="info">
  <CalloutTitle>
    Info
  </CalloutTitle>

  <CalloutDescription>
    If `parameters.enable_error_message` is set to `true` when starting the agent, greeting audio URL errors are also delivered to the client via the `onMessageError` RTM callback, in addition to the server-side webhook event.
  </CalloutDescription>
</CalloutContainer>

### 111 agent metrics [#111-agent-metrics]

An `eventType` of `111` notifies the performance metrics of an agent. The `payload` contains the following fields:

<ParameterList title="payload">
  <Parameter name="agent_id" type="string">
    Unique identifier of the agent.
  </Parameter>

  <Parameter name="name" type="string">
    The agent name provided when calling [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join). Unique within a channel.
  </Parameter>

  <Parameter name="start_ts" type="integer">
    Timestamp indicating when the agent was created and joined the channel.
  </Parameter>

  <Parameter name="stop_ts" type="integer">
    Timestamp indicating when the agent stopped and left the channel.
  </Parameter>

  <Parameter name="channel" type="string">
    The name of the channel where the agent is located.
  </Parameter>

  <Parameter name="metrics" type="array">
    An array of performance metrics. Each object contains the following fields:

    <Parameter name="turn_id" type="string">
      Dialogue round ID.
    </Parameter>

    <Parameter name="asr_ttlw" type="integer">
      The ttlw (Time To Last Word) metric of the ASR module. Represents the delay (in milliseconds) from when the user finishes speaking until the last word is output by the ASR.
    </Parameter>

    <Parameter name="llm_ttfb" type="integer">
      The ttfb (Time To First Byte) metric for the LLM module. Represents the latency (in milliseconds) from the start of an LLM request to the receipt of the first byte of the response.
    </Parameter>

    <Parameter name="llm_ttfs" type="integer">
      The ttfs (Time To First Sentence) metric for the LLM module. Represents the time (in milliseconds) elapsed from the start of an LLM request to the receipt of the first complete sentence response.
    </Parameter>

    <Parameter name="tts_ttfb" type="integer">
      The ttfb (Time To First Byte) metric for the TTS module. Represents the latency (in milliseconds) from the start of a TTS request to the receipt of the first byte of the response.
    </Parameter>
  </Parameter>

  <Parameter name="labels" type="object" required="false">
    Custom labels in key-value pair format. Contains the same labels that were set when starting the agent.
  </Parameter>
</ParameterList>

#### Payload example [#payload-example-2]

```json
{
  "agent_id": "A42AC47Hxxxxxxxx4PK27ND25E",
  "name": "my-agent",
  "start_ts": 1000,
  "stop_ts": 1672531200,
  "channel": "test-channel",
  "metrics": [
      {
          "turn_id": 1,
          "asr_ttlw": 503,
          "llm_ttfb": 1104,
          "tts_ttfb": 85
      },
      {
          "turn_id": 2,
          "asr_ttlw": 2385,
          "llm_ttfb": 980,
          "tts_ttfb": 78
      }
  ],
  "labels": {
    "campaign_id": "test_campaign",
    "customer_group": "vip"
  }
}
```

### 112 turns finished [#112-turns-finished]

An `eventType` of `112` indicates a batch callback of conversation turn data after the session ends. This event returns the conversation turns for the current session in a single callback, making it convenient for post-session analysis, archiving, or offline processing.

When a session has more than 200 turns, the callback data may be truncated. Use the `is_truncated` field to check whether the current callback contains the complete turn data.

The `payload` contains the following fields:

<ParameterList title="payload">
  <Parameter name="agent_id" type="string">
    Unique identifier of the agent.
  </Parameter>

  <Parameter name="name" type="string">
    The agent name provided when calling [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join). Unique within a channel.
  </Parameter>

  <Parameter name="channel" type="string">
    The name of the channel where the agent is located.
  </Parameter>

  <Parameter name="start_ts" type="number">
    Timestamp indicating when the agent was created and joined the channel.
  </Parameter>

  <Parameter name="stop_ts" type="number">
    Timestamp indicating when the agent stopped and left the channel.
  </Parameter>

  <Parameter name="total_turn_count" type="number">
    The total number of conversation turns in the session.
  </Parameter>

  <Parameter name="is_truncated" type="boolean">
    Whether the turn data in the current callback is truncated. A value of `true` indicates that the current callback did not return all turns.
  </Parameter>

  <Parameter name="labels" type="object" required="false">
    Custom labels in key-value pair format. Contains the same labels that were set when starting the agent. Only returned if labels were passed in when creating the agent.
  </Parameter>

  <Parameter name="turns" type="array[object]">
    A list of conversation turns for the session.

    <Parameter name="agent_id" type="string">
      Unique identifier of the agent.
    </Parameter>

    <Parameter name="channel" type="string">
      The name of the channel where the agent is located.
    </Parameter>

    <Parameter name="turn_id" type="number">
      The sequential index of the turn within the session. Starts at `1`.
    </Parameter>

    <Parameter name="start" type="object">
      Details about the start of the turn.

      <Parameter name="start_at" type="number">
        The Unix timestamp in milliseconds (UTC time) when the turn started.
      </Parameter>

      <Parameter name="type" type="string" possibleValues="voice_input, greeting, silence_timeout, api_speak, api_think">
        The type of event that initiated the turn.
      </Parameter>

      <Parameter name="metadata" type="object">
        Additional context about the turn start event. Included fields depend on the value of the `type` field.

        <Parameter name="speech_duration_ms" type="integer">
          The duration of the user's voice input in milliseconds. Included only when `type` is `voice_input`.
        </Parameter>

        <Parameter name="interrupt_duration_ms" type="integer">
          The minimum voice duration in milliseconds required to trigger an interruption. Included only when `type` is `voice_input`.
        </Parameter>
      </Parameter>
    </Parameter>

    <Parameter name="end" type="object">
      Details about the end of the turn.

      <Parameter name="end_at" type="number">
        The Unix timestamp in milliseconds (UTC time) when the turn ended.
      </Parameter>

      <Parameter name="type" type="string" possibleValues="ok, error, ignored, interrupted">
        The type of event that ended the turn.
      </Parameter>

      <Parameter name="metadata" type="object">
        Additional context about the turn end event.
      </Parameter>
    </Parameter>

    <Parameter name="metrics" type="object">
      Latency metrics for the turn.

      <Parameter name="e2e_latency_ms" type="number">
        The end-to-end latency in milliseconds for the turn. Represents the time from when the user finishes speaking to when the agent starts speaking.
      </Parameter>

      <Parameter name="segmented_latency_ms" type="object">
        A breakdown of latency by segment.

        <Parameter name="algorithm_processing" type="number">
          Algorithm processing delay in milliseconds.
        </Parameter>

        <Parameter name="asr_ttlw" type="number">
          The ASR Time To Last Word (TTLW) in milliseconds. Represents the delay from when the user finishes speaking to when the ASR module outputs the last word.
        </Parameter>

        <Parameter name="llm_ttft" type="number">
          The LLM Time To First Token (TTFT) in milliseconds. Represents the delay from when the LLM receives the request to when it outputs the first token.
        </Parameter>

        <Parameter name="llm_ftfs" type="number">
          The LLM First Token To First Sentence (FTFS) in milliseconds. Represents the delay from when the LLM outputs the first token to when it outputs the first complete sentence.
        </Parameter>

        <Parameter name="tts_ttfb" type="number">
          The TTS Time To First Byte (TTFB) in milliseconds. Represents the delay from when the TTS module receives a text request to when it outputs the first audio byte.
        </Parameter>

        <Parameter name="transport" type="number">
          Network transmission delay in milliseconds. Not returned when the user is connected using the RTC Web SDK.
        </Parameter>
      </Parameter>
    </Parameter>
  </Parameter>
</ParameterList>

#### Payload example [#payload-example-3]

```json
{
  "agent_id": "xxxx",
  "name": "support_agent_001",
  "channel": "xxxx",
  "start_ts": 1715000000000,
  "stop_ts": 1715000015000,
  "total_turn_count": 250,
  "is_truncated": true,
  "labels": {
    "campaign_id": "test_campaign",
    "customer_group": "vip"
  },
  "turns": [
    {
      "agent_id": "xxxx",
      "channel": "xxxx",
      "turn_id": 1,
      "start": {
        "start_at": 1774579820147,
        "type": "voice_input"
      },
      "end": {
        "end_at": 1774579822412,
        "type": "ok"
      },
      "metrics": {
        "e2e_latency_ms": 1500,
        "segmented_latency_ms": {
          "algorithm_processing": 300,
          "asr_ttlw": 200,
          "llm_ttft": 600,
          "tts_ttfb": 200,
          "transport": 300
        }
      }
    }
  ]
}
```

### 201 inbound call state [#201-inbound-call-state]

An `eventType` of `201` notifies changes in the status of an incoming call. The `payload` contains the following fields:

<ParameterList title="payload">
  <Parameter name="agent_id" type="string">
    Unique identifier of the agent.
  </Parameter>

  <Parameter name="name" type="string">
    The agent name provided when calling [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join). Unique within a channel.
  </Parameter>

  <Parameter name="channel" type="string">
    The name of the channel where the agent is located.
  </Parameter>

  <Parameter name="state" type="string" possibleValues="START, ANSWERED, TRANSFERED, HANGUP">
    Incoming call status:

    * `START`: Call received
    * `ANSWERED`: Call answered
    * `TRANSFERED`: Transfer to human operator
    * `HANGUP`: Call hung up
  </Parameter>

  <Parameter name="report_ms" type="integer">
    Timestamp (in milliseconds) of the state change.
  </Parameter>

  <Parameter name="labels" type="object" required="false">
    Custom labels in key-value pair format. Contains the same labels that were set when starting the agent.
  </Parameter>
</ParameterList>

#### Payload example [#payload-example-4]

```json
{
  "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
  "name": "my-agent",
  "channel": "xxxxx",
  "state": "START",
  "report_ms": 1737111452000,
  "labels": {
    "campaign_id": "test_campaign",
    "customer_group": "vip"
  }
}
```

### 202 outbound call state [#202-outbound-call-state]

An `eventType` of `202` notifies changes in the status of an outgoing call. The `payload` contains the following fields:

<ParameterList title="payload">
  <Parameter name="agent_id" type="string">
    Unique identifier of the agent.
  </Parameter>

  <Parameter name="name" type="string">
    The agent name provided when calling [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join). Unique within a channel.
  </Parameter>

  <Parameter name="channel" type="string">
    The name of the channel where the agent is located.
  </Parameter>

  <Parameter name="state" type="string" possibleValues="START, CALLING, RINGING, ANSWERED, HANGUP">
    Outgoing call status:

    * `START`: Call begins
    * `CALLING`: Making a phone call
    * `RINGING`: The telephone is ringing
    * `ANSWERED`: The call was connected
    * `HANGUP`: Call hung up
  </Parameter>

  <Parameter name="report_ms" type="integer">
    Timestamp (in milliseconds) of the state change.
  </Parameter>

  <Parameter name="labels" type="object" required="false">
    Custom labels in key-value pair format. Contains the same labels that were set when starting the agent.
  </Parameter>
</ParameterList>

#### Payload example [#payload-example-5]

```json
{
  "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
  "name": "my-agent",
  "channel": "xxxxx",
  "state": "CALLING",
  "report_ms": 1737111452000,
  "labels": {
    "campaign_id": "test_campaign",
    "customer_group": "vip"
  }
}
```