# ConversationalAIAPI 类 (/zh-CN/api-reference/conversational-ai/web/conversationalaiapi) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 用于通过声网的 RTC 和 RTM 服务管理对话式 AI 引擎交互的类。 :::info[信息] 自 1.7.0 版本新增。 ::: ## chat [#chat] ```typescript public async chat(agentUserId: string, message: IChatMessageText | IChatMessageImage) ``` 向对话式智能体发送聊天消息。 :::info[信息] 自 1.7.0 版本新增。 ::: #### 示例代码 [#示例代码] ```typescript // Send an image message const imageMessage: IChatMessageImage = { messageType: EChatMessageType.IMAGE, imageData: urlImageData }; await api.chat("user123", imageMessage); ``` #### 参数 [#参数] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `agentUserId` | `string` | 智能体的唯一标识符。 | | `message` | `IChatMessageText \| IChatMessageImage` | 要发送的聊天消息,类型为 [`IChatMessageImage`](/zh-CN/api-reference/conversational-ai/web/struct#ichatmessageimage),详见 [`IChatMessageImage`](/zh-CN/api-reference/conversational-ai/web/struct#ichatmessageimage)。 | #### 返回值 [#返回值] 方法调用成功,返回一个 `Promise`,表示消息发送结果。 ## speak [#speak] ```typescript public async speak(agentUserId: string, message: SpeakMessage): Promise ``` 绕过大模型,直接通过智能体的 TTS 流程播报文本。 该方法需要在初始化时传入 `rtmEngine`。Promise 成功仅表示 RTM 消息发布成功,不代表智能体已经完成播报。 #### 参数 [#参数-1] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `agentUserId` | `string` | 智能体用户 ID。 | | `message` | `SpeakMessage` | 播报内容和播报行为配置。详见 [`SpeakMessage`](/zh-CN/api-reference/conversational-ai/web/struct#speakmessage)。 | ## think [#think] ```typescript public async think(agentUserId: string, message: ThinkMessage): Promise ``` 将文本作为用户输入注入对话,并交由大模型处理。 该方法需要在初始化时传入 `rtmEngine`。Promise 成功仅表示 RTM 消息发布成功,不代表大模型已经完成处理。 #### 参数 [#参数-2] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `agentUserId` | `string` | 智能体用户 ID。 | | `message` | `ThinkMessage` | 指令内容、状态动作和自定义元数据。详见 [`ThinkMessage`](/zh-CN/api-reference/conversational-ai/web/struct#thinkmessage)。 | ## getInstance [#getinstance] ```typescript public static getInstance() ``` 获取 [`ConversationalAIAPI`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi) 的单例实例。 :::info[信息] 自 1.6.0 版本新增。 ::: 该方法确保在整个应用程序生命周期中只存在一个 [`ConversationalAIAPI`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi) 实例。调用前必须先执行 [`init`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi#init) 方法进行初始化,否则会抛出异常。 #### 返回值 [#返回值-1] 方法调用成功,返回 [`ConversationalAIAPI`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi) 实例。 ## init [#init] ```typescript public static init(cfg: IConversationalAIAPIConfig) ``` 初始化 [`ConversationalAIAPI`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi) 单例实例。 :::info[信息] 自 1.6.0 版本新增。 ::: 该方法用于设置 RTC 和 RTM 引擎、渲染模式以及日志选项。必须在调用 [`ConversationalAIAPI`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi) 的其他方法之前调用此方法。 - 同一时间只能初始化一个实例。 - 如果已初始化,将抛出错误 #### 参数 [#参数-3] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `cfg` | `IConversationalAIAPIConfig` | 用于初始化 API 的配置对象,详见 `IConversationalAIAPIConfig`。 | #### 返回值 [#返回值-2] 方法调用成功,返回初始化后的 [`ConversationalAIAPI`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi) 实例。 ## subscribeMessage [#subscribemessage] ```typescript public subscribeMessage(channel: string) ``` 订阅消息频道以获取实时更新。 :::info[信息] 自 1.6.0 版本新增。 ::: 该方法绑定必要的 RTC 和 RTM 事件,并启动 `CovSubRenderController` 以处理接收到的消息。 :::warning[注意] - 使用此方法前必须调用 [`init`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi#init)。 - 如果未初始化将抛出错误。 ::: #### 参数 [#参数-4] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `channel` | `string` | 要订阅消息的频道名。 | ## unsubscribe [#unsubscribe] ```typescript public unsubscribe() ``` 取消订阅消息频道并清理资源。 :::info[信息] 自 1.6.0 版本新增。 ::: 该方法解绑 RTC 和 RTM 事件,清空频道,并清理 `CovSubRenderController`。 :::warning[注意] - 使用此方法前必须调用 [`subscribeMessage`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi#subscribemessage)。 - 如果未初始化将抛出错误。 ::: ## destroy [#destroy] ```typescript public destroy(): void ``` 销毁 [`ConversationalAIAPI`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi) 实例并清理资源。 :::info[信息] 自 1.6.0 版本新增。 ::: 该方法会解绑所有 RTC 和 RTM 事件,清空频道场景,并清理 `CovSubRenderController`。 :::warning[注意] - 使用该方法前必须调用 [`unsubscribe`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi#unsubscribe)。 - 如果未初始化,则会抛出错误。 ::: ## interrupt [#interrupt] ```typescript public async interrupt(agentUserId: string) ``` 向指定的智能体发送中断消息。 :::info[信息] 自 1.6.0 版本新增。 ::: :::warning[注意] - 使用该方法前必须调用 [`init`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi#init)。 - 如果未初始化或发送失败,将抛出错误。 ::: #### 参数 [#参数-5] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `agentUserId` | `string` | 要中断的智能体的用户 ID。 | ## manualSOS [#manualsos] ```typescript public async manualSOS(agentUserId: string): Promise ``` 通过 RTM 向智能体发送手动 SoS 信令,显式声明当前用户开始说话。 :::warning[注意] - `requestId` 由组件内部生成。发起请求后,方法返回本次请求对应的 `requestId`,业务方可自行保存,用于关联服务端回调。 - 方法返回成功只表示 RTM publish 成功,不代表服务端已处理成功。 - 服务端是否成功处理本次请求,需要以后续 `USER_MANUAL_SOS_RESULT` 或 `USER_MANUAL_EOS_RESULT` 事件结果为准。 - 客户端不本地判断当前是否为 manual mode,mode 校验交给服务端。 ::: #### 参数 [#参数-6] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `agentUserId` | `string` | 智能体的唯一标识符。 | #### 返回值 [#返回值-3] 方法调用成功,返回一个 `Promise`,其解析值为本次请求对应的 `requestId`。该返回结果仅表示 RTM publish 成功,不代表服务端已处理成功。 ## manualEOS [#manualeos] ```typescript public async manualEOS(agentUserId: string): Promise ``` 通过 RTM 向智能体发送手动 EoS 信令,显式声明当前用户结束说话。 :::warning[注意] - `requestId` 由组件内部生成。发起请求后,方法返回本次请求对应的 `requestId`,业务方可自行保存,用于关联服务端回调。 - 方法返回成功只表示 RTM publish 成功,不代表服务端已处理成功。 - 服务端是否成功处理本次请求,需要以后续 `USER_MANUAL_SOS_RESULT` 或 `USER_MANUAL_EOS_RESULT` 事件结果为准。 - 客户端不本地判断当前是否为 manual mode,mode 校验交给服务端。 ::: #### 参数 [#参数-7] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `agentUserId` | `string` | 智能体的唯一标识符。 | #### 返回值 [#返回值-4] 方法调用成功,返回一个 `Promise`,其解析值为本次请求对应的 `requestId`。该返回结果仅表示 RTM publish 成功,不代表服务端已处理成功。