# IConversationalAIAPI 类 (/zh-CN/api-reference/conversational-ai/android/iconversationalaiapi)

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

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

```kotlin
fun chat(agentUserId: String, message: ChatMessage, completion: (error: ConversationalAIAPIError?) -> Unit)
```

向智能体发送消息。

支持通过 [`ChatMessage`](/zh-CN/api-reference/conversational-ai/android/struct#chatmessage) 密封类层级发送不同类型的消息：

- [`ImageMessage`](/zh-CN/api-reference/conversational-ai/android/struct#imagemessage)：用于发送图片消息。

#### 参数 [#参数]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `message` | `ChatMessage` | 消息对象，类型为 [`ImageMessage`](/zh-CN/api-reference/conversational-ai/android/struct#imagemessage)。详见 [`ChatMessage`](/zh-CN/api-reference/conversational-ai/android/struct#chatmessage)。 |
| `completion` | `(error: ConversationalAIAPIError?) -> Unit` | 回调函数。调用成功时 `error` 为 null，失败时为非 null。 |

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

```kotlin
fun speak(agentUserId: String, message: SpeakMessage, completion: (error: ConversationalAIAPIError?) -> Unit)
```

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

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

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

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `message` | `SpeakMessage` | 播报内容和播报行为配置。详见 [`SpeakMessage`](/zh-CN/api-reference/conversational-ai/android/struct#speakmessage)。 |
| `completion` | `(error: ConversationalAIAPIError?) -> Unit` | 回调函数。调用成功时 `error` 为 null，失败时为非 null。 |

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

```kotlin
fun think(agentUserId: String, message: ThinkMessage, completion: (error: ConversationalAIAPIError?) -> Unit)
```

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

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

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

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `message` | `ThinkMessage` | 指令内容、状态动作和自定义元数据。详见 [`ThinkMessage`](/zh-CN/api-reference/conversational-ai/android/struct#thinkmessage)。 |
| `completion` | `(error: ConversationalAIAPIError?) -> Unit` | 回调函数。调用成功时 `error` 为 null，失败时为非 null。 |

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

```kotlin
fun addHandler(handler: IConversationalAIAPIEventHandler)
```

注册事件处理器，用于接收智能体会话事件。

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

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `handler` | `IConversationalAIAPIEventHandler` | 事件处理器实例，详见 [`IConversationalAIAPIEventHandler`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapieventhandler)。 |

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

```kotlin
fun removeHandler(handler: IConversationalAIAPIEventHandler)
```

移除已注册的事件处理器。

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

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `handler` | `IConversationalAIAPIEventHandler` | 事件处理器实例，详见 [`IConversationalAIAPIEventHandler`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapieventhandler)。 |

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

```kotlin
fun subscribeMessage(channelName: String, completion: (error: ConversationalAIAPIError?) -> Unit)
```

订阅频道以接收智能体对话事件。

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

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `channelName` | `String` | 频道名。 |
| `completion` | `(error: ConversationalAIAPIError?) -> Unit` | 回调函数。调用成功时，`error` 为 null；调用失败时，`error` 为非 null。详见 [`ConversationalAIAPIError`](/zh-CN/api-reference/conversational-ai/android/struct#conversationalaiapierror)。 |

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

```kotlin
fun unsubscribeMessage(channelName: String, completion: (error: ConversationalAIAPIError?) -> Unit)
```

取消订阅频道名，并停止接收事件。

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

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `channelName` | `String` | 频道名。 |
| `completion` | `(error: ConversationalAIAPIError?) -> Unit` | 异步通知取消订阅结果的回调。成功时 `error` 为 null，失败时为非 null，详见 [`ConversationalAIAPIError`](/zh-CN/api-reference/conversational-ai/android/struct#conversationalaiapierror)。 |

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

```kotlin
fun interrupt(agentUserId: String, completion: (error: ConversationalAIAPIError?) -> Unit)
```

中断智能体的发言。

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

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `completion` | `(error: ConversationalAIAPIError?) -> Unit` | 异步回调函数。调用成功时，`error` 为 null；调用失败时，`error` 为非 null，包含错误信息，详见 [`ConversationalAIAPIError`](/zh-CN/api-reference/conversational-ai/android/struct#conversationalaiapierror)。 |

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

```kotlin
fun manualSOS(agentUserId: String, completion: (requestId: String, error: ConversationalAIAPIError?) -> Unit)
```

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

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

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

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `completion` | `(requestId: String, error: ConversationalAIAPIError?) -> Unit` | 异步回调函数。`requestId` 为本次请求的唯一标识符；调用成功时，`error` 为 null；调用失败时，`error` 为非 null。该回调仅表示 RTM publish 是否成功。 |

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

```kotlin
fun manualEOS(agentUserId: String, completion: (requestId: String, error: ConversationalAIAPIError?) -> Unit)
```

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

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

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

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `completion` | `(requestId: String, error: ConversationalAIAPIError?) -> Unit` | 异步回调函数。`requestId` 为本次请求的唯一标识符；调用成功时，`error` 为 null；调用失败时，`error` 为非 null。该回调仅表示 RTM publish 是否成功。 |

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

```kotlin
fun loadAudioSettings(scenario: Int = Constants.AUDIO_SCENARIO_AI_CLIENT)
```

设置音频参数以优化智能体对话性能。

:::warning[注意]
你必须在每次调用 `joinChannel` 之前调用此方法，以确保最佳音频质量。
:::

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

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `scenario` | `Int` | [iconversationalaiapi-android-html-8-1-2 details](#table-slot-iconversationalaiapi-android-html-8-1-2) |

<a id="table-slot-iconversationalaiapi-android-html-8-1-2"></a>

**iconversationalaiapi-android-html-8-1-2 details**

音频场景，默认值为 `AUDIO_SCENARIO_AI_CLIENT`。

- `AUDIO_SCENARIO_AI_CLIENT`：用于智能体对话场景，优化语音识别和语义理解的音频质量。

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

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

```kotlin
fun destroy()
```

销毁 `API` 实例并释放资源。

调用该方法释放所有资源。调用后，该实例将无法再次使用。建议在不再需要该实例时调用该方法。