需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

ConversationalAIAPI 类

  • iOS

更新时间不可用

chat

Swift
@objc func chat(agentUserId: String, message: ChatMessage, completion: @escaping (ConversationalAIAPIError?) -> Void)

向智能体发送消息以进行处理。

你可以使用该方法将文字和图片的消息发送给智能体，并通过完成回调指示操作的成功或失败。

参数

参数数据类型描述
agentUserIdString智能体的 RTM 用户 ID，必须全局唯一。
messageChatMessage消息对象，包含图片 URL。详见 ChatMessage。
completion@escaping (ConversationalAIAPIError?) -> Void

操作完成时调用的回调函数。

表格内容超出当前宽度，可横向滚动查看更多列。

speak

Swift
@objc func speak(agentUserId: String, message: SpeakMessage, completion: @escaping (ConversationalAIAPIError?) -> Void)

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

该方法需要 RTM。回调仅表示 RTM 消息是否发布成功，不代表智能体已经完成播报。

参数

参数数据类型描述
agentUserIdString智能体的 RTM 用户 ID，必须全局唯一。
messageSpeakMessage播报内容和播报行为配置。详见 SpeakMessage。
completion@escaping (ConversationalAIAPIError?) -> Void操作完成时调用的回调函数。成功时返回 nil，失败时返回错误信息。
表格内容超出当前宽度，可横向滚动查看更多列。

think

Swift
@objc func think(agentUserId: String, message: ThinkMessage, completion: @escaping (ConversationalAIAPIError?) -> Void)

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

该方法需要 RTM。回调仅表示 RTM 消息是否发布成功，不代表大模型已经完成处理。

参数

参数数据类型描述
agentUserIdString智能体的 RTM 用户 ID，必须全局唯一。
messageThinkMessage指令内容、状态动作和自定义元数据。详见 ThinkMessage。
completion@escaping (ConversationalAIAPIError?) -> Void操作完成时调用的回调函数。成功时返回 nil，失败时返回错误信息。
表格内容超出当前宽度，可横向滚动查看更多列。

interrupt

Swift
@objc func interrupt(agentUserId: String, completion: @escaping (ConversationalAIAPIError?) -> Void)

中断智能体当前正在进行的语音或任务处理。

使用该方法可以中断当前正在说话或处理任务的 智能体。

注意

  • 如果 error 有值，表示消息发送失败。
    • 如果 error 为 nil，表示消息发送成功，但不保证智能体成功被中断。

参数

参数数据类型描述
agentUserIdString智能体的 RTM 用户 ID，必须全局唯一。
completion(ConversationalAIAPIError?) -> Void操作完成时的回调函数。你可以通过该回调的 error 参数得知操作的结果或错误信息，详见 ConversationalAIAPIError。
表格内容超出当前宽度，可横向滚动查看更多列。

manualSOS

Swift
@objc func manualSOS(agentUserId: String, completion: @escaping (String, ConversationalAIAPIError?) -> Void)

通过 RTM 向智能体发送手动 SoS 信令，显式声明当前用户开始说话。

注意

  • requestId 由组件内部生成。发起请求后，组件会在 completion 中返回本次请求对应的 requestId，业务方可自行保存，用于关联服务端回调。
  • completion 只表示 RTM publish 是否成功，不代表服务端已处理成功。
  • 服务端是否成功处理本次请求，需要以后续 onUserManualSosEvent 或 onUserManualEosEvent 回调结果为准。
  • 客户端不本地判断当前是否为 manual mode，mode 校验交给服务端。
  • 常见失败原因包括：当前 mode 配置不允许手动信令、当前不存在可标记的活跃用户发言、同一轮内重复提交已生效的手动 SoS 或手动 EoS。

参数

参数数据类型描述
agentUserIdString智能体的 RTM 用户 ID，必须全局唯一。
completion@escaping (String, ConversationalAIAPIError?) -> Void操作完成时调用的回调函数。第一个参数为本次请求的唯一标识符 requestId；第二个参数为错误信息，成功时返回 nil。该回调仅表示 RTM publish 是否成功。
表格内容超出当前宽度，可横向滚动查看更多列。

manualEOS

Swift
@objc func manualEOS(agentUserId: String, completion: @escaping (String, ConversationalAIAPIError?) -> Void)

通过 RTM 向智能体发送手动 EoS 信令，显式声明当前用户结束说话。

注意

  • requestId 由组件内部生成。发起请求后，组件会在 completion 中返回本次请求对应的 requestId，业务方可自行保存，用于关联服务端回调。
  • completion 只表示 RTM publish 是否成功，不代表服务端已处理成功。
  • 服务端是否成功处理本次请求，需要以后续 onUserManualSosEvent 或 onUserManualEosEvent 回调结果为准。
  • 客户端不本地判断当前是否为 manual mode，mode 校验交给服务端。
  • 常见失败原因包括：当前 mode 配置不允许手动信令、当前不存在可标记的活跃用户发言、同一轮内重复提交已生效的手动 SoS 或手动 EoS。

参数

参数数据类型描述
agentUserIdString智能体的 RTM 用户 ID，必须全局唯一。
completion@escaping (String, ConversationalAIAPIError?) -> Void操作完成时调用的回调函数。第一个参数为本次请求的唯一标识符 requestId；第二个参数为错误信息，成功时返回 nil。该回调仅表示 RTM publish 是否成功。
表格内容超出当前宽度，可横向滚动查看更多列。

loadAudioSettings[1/2]

Swift
@objc func loadAudioSettings()

设置音频最佳实践参数以获得最佳性能。

设置用于智能体对话中实现最佳性能所需的音频参数。默认使用 .aiClient 音频场景。

示例代码：

Swift
// 在加入频道前设置音频最佳实践参数
api.loadAudioSettings()  // 使用默认场景

// 然后加入频道
rtcEngine.joinChannel(byToken: token, channelId: channelName, info: nil, uid: userId)

注意

重要：如果你需要启用音频最佳实践，必须在每次调用 joinChannel 之前调用此方法。

loadAudioSettings[2/2]

Objective-C
@objc func loadAudioSettings(secnario: AgoraAudioScenario)

设置特定场景下的音频最佳实践参数。

你可以通过此方法配置在智能体对话中实现最佳性能所需的音频参数。

注意

如果你需要启用音频最佳实践，必须在每次调用 joinChannel 之前调用此方法。

参数

参数数据类型描述
secnarioAgoraAudioScenario

音频场景，详见 AgoraAudioScenario。

注意

如果启用数字人功能，请将场景设置为 .default 以获得更好的混音效果。

表格内容超出当前宽度，可横向滚动查看更多列。

subscribeMessage

Swift
@objc func subscribeMessage(channelName: String, completion: @escaping (ConversationalAIAPIError?) -> Void)

订阅频道消息。

设置频道参数并注册消息订阅回调。该方法在频道发生变化时调用，通常在智能体启动时被调用。

参数

参数数据类型描述
channelNameString要订阅的频道名。
completion(ConversationalAIAPIError?) -> Void订阅失败时返回错误信息的回调，详见 ConversationalAIAPIError。
表格内容超出当前宽度，可横向滚动查看更多列。

unsubscribeMessage

Swift
@objc func unsubscribeMessage(channelName: String, completion: @escaping (ConversationalAIAPIError?) -> Void)

取消订阅频道消息。

调用该方法可停止接收指定频道的消息，适用于与智能体断开连接的场景。

参数

参数数据类型描述
channelNameString要取消订阅的频道名。
completion(ConversationalAIAPIError?) -> Void取消订阅操作完成后的回调。你可以通过该回调获取错误信息，详见 ConversationalAIAPIError。
表格内容超出当前宽度，可横向滚动查看更多列。

addHandler

Swift
@objc func addHandler(handler: ConversationalAIAPIEventHandler)

添加事件处理器以接收回调。

你可以注册一个代理，用于接收会话事件、状态变更以及其他通知。

参数

参数数据类型描述
handlerConversationalAIAPIEventHandler事件处理器，需实现 ConversationalAIAPIEventHandler 协议。详见 ConversationalAIAPIEventHandler。
表格内容超出当前宽度，可横向滚动查看更多列。

removeHandler

Swift
@objc func removeHandler(handler: ConversationalAIAPIEventHandler)

移除事件处理器。

参数

参数数据类型描述
handlerConversationalAIAPIEventHandler要移除的事件处理器。详见 ConversationalAIAPIEventHandler。
表格内容超出当前宽度，可横向滚动查看更多列。

destroy

Swift
@objc func destroy()

销毁 API 实例并释放所有资源。

调用该方法可销毁当前 API 实例并释放所有资源。调用后，该实例将无法再次使用。请在不再需要使用 destroy 方法所属的 API 时调用此方法。

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利