# 结构体 (/zh-CN/api-reference/conversational-ai/web/struct) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## IConversationalAIAPIEventHandlers [#iconversationalaiapieventhandlers] ```typescript export interface IConversationalAIAPIEventHandlers ``` 用于对话式 AI 引擎 API 模块的事件处理器接口。 :::info[信息] 自 1.6.0 版本新增。 ::: ## TMessageReceipt [#tmessagereceipt] ```typescript export type TMessageReceipt = { moduleType: EModuleType messageType: EChatMessageType message: string turnId: number } ``` 消息回执类型定义。 :::info[信息] 自 1.7.0 版本新增。 ::: #### 成员参数 [#成员参数] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `moduleType` | `EModuleType` | 发送该消息的模块类型。详见 [`EModuleType`](/zh-CN/api-reference/conversational-ai/web/enum#emoduletype)。 | | `messageType` | `EChatMessageType` | 消息的类型。详见 [`EChatMessageType`](/zh-CN/api-reference/conversational-ai/web/enum#echatmessagetype)。 | | `message` | `string` | 消息的内容。 | | `turnId` | `number` | 会话轮次的唯一标识符。 | ## TUserManualEventPayload [#tusermanualeventpayload] ```typescript export type TUserManualEventPayload = { success: boolean requestId: string turnId?: number errorMessage?: string } ``` 手动 SoS/EoS 通用载荷。 #### 成员参数 [#成员参数-1] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `success` | `boolean` | 服务端是否成功处理本次手动信令。 | | `requestId` | `string` | 请求 ID,与调用 `manualSOS` 或 `manualEOS` 后返回的 `requestId` 对应。 | | `turnId` | `number` | 关联的对话轮次 ID。服务端失败回调未携带 `turn_id` 时可为空。 | | `errorMessage` | `string` | 服务端返回的原始错误信息。成功时通常为空。 | ## TUserManualSosEvent [#tusermanualsosevent] ```typescript export type TUserManualSosEvent = { eventId: string timestamp: number payload: TUserManualEventPayload } ``` 手动 SoS 事件对象。 #### 成员参数 [#成员参数-2] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `eventId` | `string` | 事件唯一 ID。 | | `timestamp` | `number` | 事件时间戳,单位为毫秒。 | | `payload` | `TUserManualEventPayload` | 事件载荷。详见 [`TUserManualEventPayload`](/zh-CN/api-reference/conversational-ai/web/struct#tusermanualeventpayload)。 | ## TUserManualEosEvent [#tusermanualeosevent] ```typescript export type TUserManualEosEvent = { eventId: string timestamp: number payload: TUserManualEventPayload } ``` 手动 EoS 事件对象。 #### 成员参数 [#成员参数-3] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `eventId` | `string` | 事件唯一 ID。 | | `timestamp` | `number` | 事件时间戳,单位为毫秒。 | | `payload` | `TUserManualEventPayload` | 事件载荷。详见 [`TUserManualEventPayload`](/zh-CN/api-reference/conversational-ai/web/struct#tusermanualeventpayload)。 | ## TAgentManualEosPayload [#tagentmanualeospayload] ```typescript export type TAgentManualEosPayload = { reason: string maxDurationMs: number turnId: number } ``` 服务端超限自动 EoS 载荷。 #### 成员参数 [#成员参数-4] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `reason` | `string` | 服务端自动结束当前用户发言的原因。 | | `maxDurationMs` | `number` | 当前配置的单轮最大音频时长,单位为毫秒。 | | `turnId` | `number` | 关联的对话轮次 ID。 | ## TAgentManualEosEvent [#tagentmanualeosevent] ```typescript export type TAgentManualEosEvent = { eventId: string timestamp: number payload: TAgentManualEosPayload } ``` 服务端超限自动 EoS 事件对象。 #### 成员参数 [#成员参数-5] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `eventId` | `string` | 事件唯一 ID。 | | `timestamp` | `number` | 事件时间戳,单位为毫秒。 | | `payload` | `TAgentManualEosPayload` | 事件载荷。详见 [`TAgentManualEosPayload`](/zh-CN/api-reference/conversational-ai/web/struct#tagentmanualeospayload)。 | ## IChatMessageBase [#ichatmessagebase] ```typescript export interface IChatMessageBase { messageType: EChatMessageType } ``` 包含基础消息类型属性的 [`IChatMessageBase`](/zh-CN/api-reference/conversational-ai/web/struct#ichatmessagebase) 接口。 :::info[信息] 自 v1.7.0 版本新增。 ::: #### 成员参数 [#成员参数-6] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `messageType` | `EChatMessageType` | 消息类型,详见 [`EChatMessageType`](/zh-CN/api-reference/conversational-ai/web/enum#echatmessagetype)。 | ## IChatMessageImage [#ichatmessageimage] ```typescript export interface IChatMessageImage extends IChatMessageBase { messageType: EChatMessageType.IMAGE uuid: string url?: string } ``` 表示一个基于图片的聊天消息,包含 `url` 形式的图片数据。 #### 成员参数 [#成员参数-7] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `messageType` | `EChatMessageType.IMAGE` | 消息类型,必须为 `IMAGE`。详见 [`EChatMessageType`](/zh-CN/api-reference/conversational-ai/web/enum#echatmessagetype)。 | | `uuid` | `string` | 图片消息的唯一标识符。 | | `url` | `string` | 可选。指向图片资源的 URL。 | ## SpeakMessage [#speakmessage] ```typescript export interface SpeakMessage { text: string priority?: EChatMessagePriority interruptable?: boolean } ``` 用于绕过大模型,直接通过智能体的 TTS 流程播报文本。 #### 成员参数 [#成员参数-8] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `text` | `string` | 要播报的文本。 | | `priority` | `EChatMessagePriority` | 播报请求的处理优先级,默认值为 `INTERRUPTED`。详见 [`EChatMessagePriority`](/zh-CN/api-reference/conversational-ai/web/enum#echatmessagepriority)。 | | `interruptable` | `boolean` | 是否允许用户说话打断本次播报,默认值为 `true`。 | ## ThinkMessage [#thinkmessage] ```typescript export interface ThinkMessage { text: string onListeningAction?: ThinkListeningAction onThinkingAction?: ThinkThinkingAction onSpeakingAction?: ThinkSpeakingAction interruptable?: boolean metadata?: Record } ``` 用于将文本作为用户输入注入对话,并交由大模型处理。 #### 成员参数 [#成员参数-9] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `text` | `string` | 要注入大模型的指令文本。 | | `onListeningAction` | `ThinkListeningAction` | 智能体处于倾听状态时的处理动作,默认值为 `INTERRUPT`。详见 [`ThinkListeningAction`](/zh-CN/api-reference/conversational-ai/web/enum#thinklisteningaction)。 | | `onThinkingAction` | `ThinkThinkingAction` | 智能体处于思考状态时的处理动作,默认值为 `IGNORE`。详见 [`ThinkThinkingAction`](/zh-CN/api-reference/conversational-ai/web/enum#thinkthinkingaction)。 | | `onSpeakingAction` | `ThinkSpeakingAction` | 智能体处于说话状态时的处理动作,默认值为 `IGNORE`。详见 [`ThinkSpeakingAction`](/zh-CN/api-reference/conversational-ai/web/enum#thinkspeakingaction)。 | | `interruptable` | `boolean` | 是否允许用户说话打断本次指令生成的响应,默认值为 `true`。 | | `metadata` | `Record` | 可选的业务自定义键值对。 | ## ISubtitleHelperItem [#isubtitlehelperitem] ```typescript export interface ISubtitleHelperItem { uid: string stream_id: number turn_id: number _time: number text: string status: ETurnStatus metadata: T | null } ``` 字幕辅助项接口。 :::info[信息] 自 1.6.0 版本新增。 ::: 定义字幕系统中单个字幕项的数据结构。包含用户 ID、流 ID、轮次 ID、时间戳、文本内容、状态和元数据等信息。 #### 成员参数 [#成员参数-10] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `uid` | `string` | 用户的唯一标识符。 | | `stream_id` | `number` | 流标识符。 | | `turn_id` | `number` | 会话中的轮次标识符。 | | `_time` | `number` | 字幕的时间戳(单位为毫秒)。 | | `text` | `string` | 字幕文本内容。 | | `status` | `ETurnStatus` | 字幕项的当前状态。详见 `ETurnStatus`。 | | `metadata` | `T \| null` | 附加的元数据信息。详见 `T`。 | ## TAgentMetric [#tagentmetric] ```typescript export type TAgentMetric = { type: EModuleType name: string value: number timestamp: number } ``` [`TAgentMetric`](/zh-CN/api-reference/conversational-ai/web/struct#tagentmetric) 用于定义智能体指标统计数据类型。 :::info[信息] 自 1.6.0 版本新增。 ::: 用于在智能体运行时存储指标数据,包括指标模块类型、名称、数值和时间戳。 #### 成员参数 [#成员参数-11] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `type` | `EModuleType` | 指标模块类型,详见 [`EModuleType`](/zh-CN/api-reference/conversational-ai/web/enum#emoduletype)。 | | `name` | `string` | 指标名称。 | | `value` | `number` | 指标数值。 | | `timestamp` | `number` | 数据采集时间戳(毫秒)。 | ## TModuleError [#tmoduleerror] ```typescript export type TModuleError = { type: EModuleType code: number message: string timestamp: number } ``` [`TModuleError`](/zh-CN/api-reference/conversational-ai/web/struct#tmoduleerror) 模块错误类型定义。 :::info[信息] 自 1.6.0 版本新增。 ::: 用于表示来自不同 AI 模块的错误信息,包括错误类型、错误码、错误信息和时间戳,便于错误处理和调试。错误码为模块特定内容,应由各模块单独说明。时间戳为 Unix 毫秒格式。错误信息应具备良好可读性,并提供可操作的信息。 #### 成员参数 [#成员参数-12] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `type` | `EModuleType` | 发生错误的模块类型,详见 [`EModuleType`](/zh-CN/api-reference/conversational-ai/web/enum#emoduletype)。 | | `code` | `number` | 模块特定的错误码。 | | `message` | `string` | 具备可读性的错误描述信息。 | | `timestamp` | `number` | 错误发生时的 Unix 毫秒时间戳。 | ## TStateChangeEvent [#tstatechangeevent] ```typescript export type TStateChangeEvent = { state: EAgentState turnID: number timestamp: number reason: string } ``` [`TStateChangeEvent`](/zh-CN/api-reference/conversational-ai/web/struct#tstatechangeevent) 为状态变更事件的数据类型定义。 :::info[信息] 自 1.6.0 版本新增。 ::: #### 成员参数 [#成员参数-13] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `state` | `EAgentState` | 语音代理的当前状态。详见 [`EAgentState`](/zh-CN/api-reference/conversational-ai/web/enum#eagentstate)。 | | `turnID` | `number` | 当前会话轮次的唯一标识符。 | | `timestamp` | `number` | 状态变更发生时的时间戳(单位为毫秒)。 | | `reason` | `string` | 状态变更的原因描述。 |