# ConversationalAIAPI 类 (/zh-CN/api-reference/conversational-ai/ios/conversationalaiapi)

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

<a id="chat"></a>
## chat [#chat]

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

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

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

#### 参数 [#参数]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID，必须全局唯一。 |
| `message` | `ChatMessage` | 消息对象，包含图片 URL。详见 [`ChatMessage`](/zh-CN/api-reference/conversational-ai/ios/struct#chatmessage)。 |
| `completion` | `@escaping (ConversationalAIAPIError?) -> Void` | [conversationalaiapi-ios-html-0-3-2 details](#table-slot-conversationalaiapi-ios-html-0-3-2) |

<a id="table-slot-conversationalaiapi-ios-html-0-3-2"></a>

**conversationalaiapi-ios-html-0-3-2 details**

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

- 成功时返回 `nil`。
- 失败时返回错误信息，详见 [`ConversationalAIAPIError`](/zh-CN/api-reference/conversational-ai/ios/struct#conversationalaiapierror)。

<a id="speak"></a>
## speak [#speak]

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

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

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

#### 参数 [#参数-1]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID，必须全局唯一。 |
| `message` | `SpeakMessage` | 播报内容和播报行为配置。详见 [`SpeakMessage`](/zh-CN/api-reference/conversational-ai/ios/struct#speakmessage)。 |
| `completion` | `@escaping (ConversationalAIAPIError?) -> Void` | 操作完成时调用的回调函数。成功时返回 `nil`，失败时返回错误信息。 |

<a id="think"></a>
## think [#think]

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

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

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

#### 参数 [#参数-2]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID，必须全局唯一。 |
| `message` | `ThinkMessage` | 指令内容、状态动作和自定义元数据。详见 [`ThinkMessage`](/zh-CN/api-reference/conversational-ai/ios/struct#thinkmessage)。 |
| `completion` | `@escaping (ConversationalAIAPIError?) -> Void` | 操作完成时调用的回调函数。成功时返回 `nil`，失败时返回错误信息。 |

<a id="interrupt"></a>
## interrupt [#interrupt]

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

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

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

:::warning[注意]
- 如果 `error` 有值，表示消息发送失败。
    - 如果 `error` 为 nil，表示消息发送成功，但不保证智能体成功被中断。
:::

#### 参数 [#参数-3]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID，必须全局唯一。 |
| `completion` | `(ConversationalAIAPIError?) -> Void` | 操作完成时的回调函数。你可以通过该回调的 `error` 参数得知操作的结果或错误信息，详见 [`ConversationalAIAPIError`](/zh-CN/api-reference/conversational-ai/ios/struct#conversationalaiapierror)。 |

<a id="manualsos"></a>
## manualSOS [#manualsos]

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

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

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

#### 参数 [#参数-4]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID，必须全局唯一。 |
| `completion` | `@escaping (String, ConversationalAIAPIError?) -> Void` | 操作完成时调用的回调函数。第一个参数为本次请求的唯一标识符 `requestId`；第二个参数为错误信息，成功时返回 `nil`。该回调仅表示 RTM publish 是否成功。 |

<a id="manualeos"></a>
## manualEOS [#manualeos]

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

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

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

#### 参数 [#参数-5]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID，必须全局唯一。 |
| `completion` | `@escaping (String, ConversationalAIAPIError?) -> Void` | 操作完成时调用的回调函数。第一个参数为本次请求的唯一标识符 `requestId`；第二个参数为错误信息，成功时返回 `nil`。该回调仅表示 RTM publish 是否成功。 |

<a id="loadaudiosettings[1/2]"></a>
## loadAudioSettings[1/2] [#loadaudiosettings12]

```swift
@objc func loadAudioSettings()
```

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

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

示例代码：

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

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

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

<a id="loadaudiosettings[2/2]"></a>
## loadAudioSettings[2/2] [#loadaudiosettings22]

```objc
@objc func loadAudioSettings(secnario: AgoraAudioScenario)
```

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

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

:::warning[注意]
如果你需要启用音频最佳实践，必须在每次调用 `joinChannel` 之前调用此方法。
:::

#### 参数 [#参数-6]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `secnario` | `AgoraAudioScenario` | [conversationalaiapi-ios-html-4-1-2 details](#table-slot-conversationalaiapi-ios-html-4-1-2) |

<a id="table-slot-conversationalaiapi-ios-html-4-1-2"></a>

**conversationalaiapi-ios-html-4-1-2 details**

音频场景，详见 [`AgoraAudioScenario`](/zh-CN/api-reference/rtc/ios/enum-audioscenariotype#AgoraAudioScenario)。

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

<a id="subscribemessage"></a>
## subscribeMessage [#subscribemessage]

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

订阅频道消息。

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

#### 参数 [#参数-7]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `channelName` | `String` | 要订阅的频道名。 |
| `completion` | `(ConversationalAIAPIError?) -> Void` | 订阅失败时返回错误信息的回调，详见 [`ConversationalAIAPIError`](/zh-CN/api-reference/conversational-ai/ios/struct#conversationalaiapierror)。 |

<a id="unsubscribemessage"></a>
## unsubscribeMessage [#unsubscribemessage]

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

取消订阅频道消息。

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

#### 参数 [#参数-8]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `channelName` | `String` | 要取消订阅的频道名。 |
| `completion` | `(ConversationalAIAPIError?) -> Void` | 取消订阅操作完成后的回调。你可以通过该回调获取错误信息，详见 [`ConversationalAIAPIError`](/zh-CN/api-reference/conversational-ai/ios/struct#conversationalaiapierror)。 |

<a id="addhandler"></a>
## addHandler [#addhandler]

```swift
@objc func addHandler(handler: ConversationalAIAPIEventHandler)
```

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

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

#### 参数 [#参数-9]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `handler` | `ConversationalAIAPIEventHandler` | 事件处理器，需实现 [`ConversationalAIAPIEventHandler`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapieventhandler) 协议。详见 [`ConversationalAIAPIEventHandler`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapieventhandler)。 |

<a id="removehandler"></a>
## removeHandler [#removehandler]

```swift
@objc func removeHandler(handler: ConversationalAIAPIEventHandler)
```

移除事件处理器。

#### 参数 [#参数-10]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `handler` | `ConversationalAIAPIEventHandler` | 要移除的事件处理器。详见 [`ConversationalAIAPIEventHandler`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapieventhandler)。 |

<a id="destroy"></a>
## destroy [#destroy]

```swift
@objc func destroy()
```

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

调用该方法可销毁当前 API 实例并释放所有资源。调用后，该实例将无法再次使用。请在不再需要使用 [`destroy`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapi#destroy) 方法所属的 API 时调用此方法。