# 结构体 (/zh-CN/api-reference/conversational-ai/android/struct)

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

<a id="messagereceipt"></a>
## MessageReceipt [#messagereceipt]

```kotlin
data class MessageReceipt(
    val type: ModuleType,
    val chatMessageType: ChatMessageType,
    val turnId: Long,
    val message: String
)
```

[`MessageReceipt`](/zh-CN/api-reference/conversational-ai/android/struct#messagereceipt) 表示消息回执信息，支持通过 `MediaInfo` 处理多种媒体类型。

#### 成员参数 [#成员参数]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `type` | `ModuleType` | 模块类型，详见 [`ModuleType`](/zh-CN/api-reference/conversational-ai/android/enum#moduletype)，例如 `llm`、`mllm`、`tts`、`context`。 |
| `chatMessageType` | `ChatMessageType` | 消息错误类型。详见 [`ChatMessageType`](/zh-CN/api-reference/conversational-ai/android/struct#chatmessagetype)。 |
| `turnId` | `Long` | 消息的轮次 ID。 |
| `message` | `String` | [struct-android-html-0-4-2 details](#table-slot-struct-android-html-0-4-2) |

<a id="table-slot-struct-android-html-0-4-2"></a>

**struct-android-html-0-4-2 details**

消息内容信息。需要根据 `type` 字段进行解析：

- `Context` 类型：通常为包含资源信息的 JSON 字符串。

<a id="chatmessagetype"></a>
## ChatMessageType [#chatmessagetype]

```kotlin
enum class ChatMessageType(val value: String) {
    Text("text"),
    Image("picture"),
    UNKNOWN("unknown");

    companion object {
        fun fromValue(value: String): ChatMessageType {
            return ChatMessageType.entries.find { it.value == value } ?: UNKNOWN
        }
    }
}
```

用于区分会话系统中不同类型的消息。

#### 成员参数 [#成员参数-1]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `value` | `String` | 用于匹配的字符串值。 |

<a id="messageerror"></a>
## MessageError [#messageerror]

```kotlin
data class MessageError(
    val chatMessageType: ChatMessageType,
    val code: Int,
    val message: String,
    val timestamp: Long
)
```

用于处理和上报消息错误信息。

#### 成员参数 [#成员参数-2]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `chatMessageType` | `ChatMessageType` | 消息错误类型。详见 [`ChatMessageType`](/zh-CN/api-reference/conversational-ai/android/struct#chatmessagetype)。 |
| `code` | `Int` | 用于识别特定错误情况的错误码。 |
| `message` | `String` | 错误描述信息，提供详细错误解释，通常为包含资源信息的 JSON 字符串。 |
| `timestamp` | `Long` | 事件发生的时间戳（自 1970 年 1 月 1 日 UTC 起的毫秒数）。 |

<a id="usermanualeventpayload"></a>
## UserManualEventPayload [#usermanualeventpayload]

```kotlin
data class UserManualEventPayload(
    val success: Boolean,
    val requestId: String,
    val turnId: Long?,
    val errorMessage: String?
)
```

手动 SoS/EoS 通用载荷。

#### 成员参数 [#成员参数-3]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `success` | `Boolean` | 服务端是否成功处理本次手动信令。 |
| `requestId` | `String` | 请求 ID，与调用 `manualSOS` 或 `manualEOS` 后在 `completion` 中返回的 `requestId` 对应。 |
| `turnId` | `Long?` | 关联的对话轮次 ID。若服务端失败回调未携带 `turn_id`，则该字段为 null。 |
| `errorMessage` | `String?` | 服务端返回的原始错误信息。成功时通常为 null。 |

<a id="usermanualsosevent"></a>
## UserManualSosEvent [#usermanualsosevent]

```kotlin
data class UserManualSosEvent(
    val eventId: String,
    val timestamp: Long,
    val payload: UserManualEventPayload
)
```

手动 SoS 事件对象。

#### 成员参数 [#成员参数-4]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `eventId` | `String` | 事件唯一 ID。 |
| `timestamp` | `Long` | 事件时间戳，单位为毫秒。 |
| `payload` | `UserManualEventPayload` | 事件载荷。详见 [`UserManualEventPayload`](/zh-CN/api-reference/conversational-ai/android/struct#usermanualeventpayload)。 |

<a id="usermanualeosevent"></a>
## UserManualEosEvent [#usermanualeosevent]

```kotlin
data class UserManualEosEvent(
    val eventId: String,
    val timestamp: Long,
    val payload: UserManualEventPayload
)
```

手动 EoS 事件对象。

#### 成员参数 [#成员参数-5]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `eventId` | `String` | 事件唯一 ID。 |
| `timestamp` | `Long` | 事件时间戳，单位为毫秒。 |
| `payload` | `UserManualEventPayload` | 事件载荷。详见 [`UserManualEventPayload`](/zh-CN/api-reference/conversational-ai/android/struct#usermanualeventpayload)。 |

<a id="agentmanualeospayload"></a>
## AgentManualEosPayload [#agentmanualeospayload]

```kotlin
data class AgentManualEosPayload(
    val reason: String,
    val maxDurationMs: Long,
    val turnId: Long
)
```

服务端超限自动 EoS 载荷。

#### 成员参数 [#成员参数-6]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `reason` | `String` | 服务端自动结束当前用户发言的原因。 |
| `maxDurationMs` | `Long` | 当前配置的单轮最大音频时长，单位为毫秒。 |
| `turnId` | `Long` | 关联的对话轮次 ID。 |

<a id="agentmanualeosevent"></a>
## AgentManualEosEvent [#agentmanualeosevent]

```kotlin
data class AgentManualEosEvent(
    val eventId: String,
    val timestamp: Long,
    val payload: AgentManualEosPayload
)
```

服务端超限自动 EoS 事件对象。

#### 成员参数 [#成员参数-7]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `eventId` | `String` | 事件唯一 ID。 |
| `timestamp` | `Long` | 事件时间戳，单位为毫秒。 |
| `payload` | `AgentManualEosPayload` | 事件载荷。详见 [`AgentManualEosPayload`](/zh-CN/api-reference/conversational-ai/android/struct#agentmanualeospayload)。 |

<a id="chatmessage"></a>
## ChatMessage [#chatmessage]

```kotlin
sealed class ChatMessage
```

用于发送给智能体的所有消息类型的密封基类。

该密封类层级结构为不同内容类型的消息提供类型安全的处理方式。

<a id="speakmessage"></a>
## SpeakMessage [#speakmessage]

```kotlin
data class SpeakMessage(
    val text: String,
    val priority: Priority = Priority.INTERRUPT,
    val interruptable: Boolean = true,
)
```

用于绕过大模型，直接通过智能体的 TTS 流程播报文本。

#### 成员参数 [#成员参数-8]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `text` | `String` | 要播报的文本。 |
| `priority` | `Priority` | 播报请求的处理优先级，默认值为 `INTERRUPT`。详见 [`Priority`](/zh-CN/api-reference/conversational-ai/android/enum#priority)。 |
| `interruptable` | `Boolean` | 是否允许用户说话打断本次播报，默认值为 `true`。 |

<a id="thinkmessage"></a>
## ThinkMessage [#thinkmessage]

```kotlin
data class ThinkMessage(
    val text: String,
    val onListeningAction: ThinkListeningAction = ThinkListeningAction.INTERRUPT,
    val onThinkingAction: ThinkThinkingAction = ThinkThinkingAction.IGNORE,
    val onSpeakingAction: ThinkSpeakingAction = ThinkSpeakingAction.IGNORE,
    val interruptable: Boolean = true,
    val metadata: Map<String, String>? = null,
)
```

用于将文本作为用户输入注入对话，并交由大模型处理。

#### 成员参数 [#成员参数-9]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `text` | `String` | 要注入大模型的指令文本。 |
| `onListeningAction` | `ThinkListeningAction` | 智能体处于倾听状态时的处理动作，默认值为 `INTERRUPT`。详见 [`ThinkListeningAction`](/zh-CN/api-reference/conversational-ai/android/enum#thinklisteningaction)。 |
| `onThinkingAction` | `ThinkThinkingAction` | 智能体处于思考状态时的处理动作，默认值为 `IGNORE`。详见 [`ThinkThinkingAction`](/zh-CN/api-reference/conversational-ai/android/enum#thinkthinkingaction)。 |
| `onSpeakingAction` | `ThinkSpeakingAction` | 智能体处于说话状态时的处理动作，默认值为 `IGNORE`。详见 [`ThinkSpeakingAction`](/zh-CN/api-reference/conversational-ai/android/enum#thinkspeakingaction)。 |
| `interruptable` | `Boolean` | 是否允许用户说话打断本次指令生成的响应，默认值为 `true`。 |
| `metadata` | `Map<String, String>?` | 可选的业务自定义键值对。为 null 时不会写入 RTM 消息。 |

<a id="transcript"></a>
## Transcript [#transcript]

```kotlin
data class Transcript constructor(
    val turnId: Long,
    val userId: String = "",
    val text: String,
    var status: TranscriptStatus,
    var type: TranscriptType
)
```

[`Transcript`](/zh-CN/api-reference/conversational-ai/android/struct#transcript) 用于渲染 UI 的完整转录消息。

#### 成员参数 [#成员参数-10]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `turnId` | `Long` | 会话轮次的唯一标识符。 |
| `userId` | `String` | 与该转录关联的用户标识符。 |
| `text` | `String` | 转录的实际文本内容。 |
| `status` | `TranscriptStatus` | 转录的当前状态。详见 [`TranscriptStatus`](/zh-CN/api-reference/conversational-ai/android/enum#transcriptstatus)。 |
| `type` | `TranscriptType` | 转录类型，例如 AGENT 或 USER。详见 [`TranscriptType`](/zh-CN/api-reference/conversational-ai/android/enum#transcripttype)。 |

<a id="moduleerror"></a>
## ModuleError [#moduleerror]

```kotlin
data class ModuleError(
    val type: ModuleType,
    val code: Int,
    val message: String,
    val timestamp: Long,
    val turnId: Long? = null
)
```

用于处理和上报 [`ModuleError`](/zh-CN/api-reference/conversational-ai/android/struct#moduleerror) 类型的智能体相关错误信息。

包含错误类型、错误码、错误描述和时间戳，便于实现错误监控、日志记录以及故障排查。

#### 成员参数 [#成员参数-11]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `type` | `ModuleType` | 错误类型，例如：LLM 调用失败、TTS 异常等。详见 [`ModuleType`](/zh-CN/api-reference/conversational-ai/android/enum#moduletype)。 |
| `code` | `Int` | 用于标识特定错误条件的错误码。 |
| `message` | `String` | 提供详细错误说明的错误描述信息。 |
| `timestamp` | `Long` | 错误发生的时间戳（从 1970 年 1 月 1 日 UTC 起的毫秒数）。 |
| `turnId` | `Long?` | （可选）图片对应的 `turnId`，用于图像上传错误。 |

<a id="imagemessage"></a>
## ImageMessage [#imagemessage]

```kotlin
data class ImageMessage(
    val uuid: String,
    val imageUrl: String,
) : ChatMessage()
```

用于向智能体发送图像内容。

支持通过 HTTP/HTTPS 链接指定图像文件。

#### 成员参数 [#成员参数-12]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `uuid` | `String` | 图像消息的唯一标识符。 |
| `imageUrl` | `String?` | HTTP/HTTPS 图像文件链接。 |

<a id="statechangeevent"></a>
## StateChangeEvent [#statechangeevent]

```kotlin
data class StateChangeEvent(
    val state: AgentState,
    val turnId: Long,
    val timestamp: Long,
)
```

表示智能体状态变更事件。

用于跟踪会话流程和更新用户界面中的状态指示，包含事件发生的时间戳。

#### 成员参数 [#成员参数-13]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `state` | `AgentState` | 当前智能体状态。包括：`silent`、`listening`、`thinking`、`speaking`。详见 [`AgentState`](/zh-CN/api-reference/conversational-ai/android/enum#agentstate)。 |
| `turnId` | `Long` | 会话轮次 ID，用于标识特定的对话轮次。 |
| `timestamp` | `Long` | 事件发生的时间戳（自 1970 年 1 月 1 日 UTC 起的毫秒数）。 |

<a id="interruptevent"></a>
## InterruptEvent [#interruptevent]

```kotlin
data class InterruptEvent(
    val turnId: Long,
    val timestamp: Long
)
```

[`InterruptEvent`](/zh-CN/api-reference/conversational-ai/android/struct#interruptevent) 表示中断事件。

通常在用户主动打断 AI 说话或系统检测到高优先级消息时触发，用于记录中断行为并进行相应处理。

#### 成员参数 [#成员参数-14]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `turnId` | `Long` | 被中断的对话轮次 ID。 |
| `timestamp` | `Long` | 中断事件发生的时间戳（自 1970 年 1 月 1 日 UTC 起的毫秒数）。 |

<a id="metric"></a>
## Metric [#metric]

```kotlin
data class Metric(
    val type: ModuleType,
    val name: String,
    val value: Double,
    val timestamp: Long
)
```

用于定义系统性能指标数据。

用于记录和传输系统性能数据。该数据可用于性能监控、系统优化和用户体验改进。

#### 成员参数 [#成员参数-15]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `type` | `ModuleType` | 指标类型。详见 [`ModuleType`](/zh-CN/api-reference/conversational-ai/android/enum#moduletype)。 |
| `name` | `String` | 指标名称，用于描述具体的性能项。 |
| `value` | `Double` | 指标值，通常为延迟时间（毫秒）或其他量化指标。 |
| `timestamp` | `Long` | 指标记录的时间戳（自 1970 年 1 月 1 日 UTC 起经过的毫秒数）。 |

<a id="conversationalaiapiconfig"></a>
## ConversationalAIAPIConfig [#conversationalaiapiconfig]

```kotlin
data class ConversationalAIAPIConfig(
    val rtcEngine: RtcEngine,
    val rtmClient: RtmClient,
    val renderMode: TranscriptRenderMode = TranscriptRenderMode.Word,
    val enableLog: Boolean = false
)
```

用于配置对话式 AI 引擎 API 所需的参数。

该类包含初始化对话式 AI 引擎 API 所需的参数配置，包括用于音频通信的 `rtcEngine`、用于实时消息传递的 `rtmClient`，以及转写渲染模式设置。

#### 成员参数 [#成员参数-16]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `rtcEngine` | `RtcEngine` | 用于音视频通信的引擎实例。详见 `RtcEngine`。 |
| `rtmClient` | `RtmClient` | 用于实时消息通信的客户端实例。详见 `RtmClient`。 |
| `renderMode` | `TranscriptRenderMode` | 转写渲染模式，默认为按词渲染。详见 [`TranscriptRenderMode`](/zh-CN/api-reference/conversational-ai/android/enum#transcriptrendermode)。 |
| `enableLog` | `Boolean` | [struct-android-html-14-4-2 details](#table-slot-struct-android-html-14-4-2) |

<a id="table-slot-struct-android-html-14-4-2"></a>

**struct-android-html-14-4-2 details**

是否启用日志记录：

- `true`：启用日志记录。
- `false`：不启用日志记录（默认）。

<a id="conversationalaiapierror"></a>
## ConversationalAIAPIError [#conversationalaiapierror]

```kotlin
sealed class ConversationalAIAPIError : Exception() {
    data class RtmError(val code: Int, val msg: String) : ConversationalAIAPIError()
    data class RtcError(val code: Int, val msg: String) : ConversationalAIAPIError()
    data class UnknownError(val msg: String) : ConversationalAIAPIError()

    val errorCode: Int
        get() = when (this) {
            is RtmError -> this.code
            is RtcError -> this.code
            is UnknownError -> -100
        }

    val errorMessage: String
        get() = when (this) {
            is RtmError -> this.msg
            is RtcError -> this.msg
            is UnknownError -> this.msg
        }
}
```

表示对话式 AI 引擎 API 中的错误类型。

#### 成员参数 [#成员参数-17]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `errorCode` | `Int` | [struct-android-html-15-1-2 details](#table-slot-struct-android-html-15-1-2) |
| `errorMessage` | `String` | 错误信息，返回具体的错误描述内容。 |

<a id="table-slot-struct-android-html-15-1-2"></a>

**struct-android-html-15-1-2 details**

错误码：

- `RtmError` 或 `RtcError` 返回具体错误码。
- `UnknownError` 返回 -100。