# 结构体 (/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` | 状态变更的原因描述。 |