# ConversationalAIAPIEventHandler 类 (/zh-CN/api-reference/conversational-ai/ios/conversationalaiapieventhandler)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## onMessageError [#onmessageerror]
```swift
@objc func onMessageError(agentUserId: String, error: MessageError)
```
消息处理发生错误时触发的回调。
该回调在消息处理过程中发生错误时被触发。例如,当发送聊天消息失败时,会返回错误信息。
#### 参数 [#参数]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `error` | `MessageError` | 消息错误对象,包含错误类型和错误信息。详见 [`MessageError`](/zh-CN/api-reference/conversational-ai/ios/struct#messageerror)。 |
## onMessageReceiptUpdated [#onmessagereceiptupdated]
```swift
@objc func onMessageReceiptUpdated(agentUserId: String, messageReceipt: MessageReceipt)
```
图像消息信息更新回调。
该回调在会话中处理图像时被触发,用于提供图像的元数据。
#### 参数 [#参数-1]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `messageReceipt` | `MessageReceipt` | 消息回执对象。详见 [`MessageReceipt`](/zh-CN/api-reference/conversational-ai/ios/struct#messagereceipt)。 |
## onUserManualSosEvent [#onusermanualsosevent]
```swift
@objc optional func onUserManualSosEvent(agentUserId: String, event: UserManualSosEvent)
```
手动 SoS 结果回调。
该回调用于接收服务端返回的手动 SoS 处理结果。服务端成功和失败都会通过该回调返回,业务侧可根据 `event.payload.success` 判断结果。
该回调有默认空实现,已有接入方无需强制实现。
#### 参数 [#参数-2]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `event` | `UserManualSosEvent` | 手动 SoS 事件对象。详见 [`UserManualSosEvent`](/zh-CN/api-reference/conversational-ai/ios/struct#usermanualsosevent)。 |
## onUserManualEosEvent [#onusermanualeosevent]
```swift
@objc optional func onUserManualEosEvent(agentUserId: String, event: UserManualEosEvent)
```
手动 EoS 结果回调。
该回调用于接收服务端返回的手动 EoS 处理结果。服务端成功和失败都会通过该回调返回,业务侧可根据 `event.payload.success` 判断结果。
该回调有默认空实现,已有接入方无需强制实现。
#### 参数 [#参数-3]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `event` | `UserManualEosEvent` | 手动 EoS 事件对象。详见 [`UserManualEosEvent`](/zh-CN/api-reference/conversational-ai/ios/struct#usermanualeosevent)。 |
## onAgentManualEosEvent [#onagentmanualeosevent]
```swift
@objc optional func onAgentManualEosEvent(agentUserId: String, event: AgentManualEosEvent)
```
服务端超限自动 EoS 通知回调。
当用户单轮音频持续时间超过服务端阈值时,服务端会主动结束当前用户发言,并通过该回调通知客户端。该事件不是 `manualEOS()` 的调用结果。
该回调有默认空实现,已有接入方无需强制实现。
#### 参数 [#参数-4]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `event` | `AgentManualEosEvent` | 服务端超限自动 EoS 事件对象。详见 [`AgentManualEosEvent`](/zh-CN/api-reference/conversational-ai/ios/struct#agentmanualeosevent)。 |
## onAgentStateChanged [#onagentstatechanged]
```swift
@objc func onAgentStateChanged(agentUserId: String, event: StateChangeEvent)
```
智能体状态变化回调。
该回调在智能体状态发生变化时触发,例如从空闲切换为静音、聆听、思考或说话状态。你可以使用该回调更新用户界面或跟踪对话流程。
#### 参数 [#参数-5]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `event` | `StateChangeEvent` | 智能体状态变化事件。详见 [`StateChangeEvent`](/zh-CN/api-reference/conversational-ai/ios/struct#statechangeevent)。 |
## onAgentListeningChanged [#onagentlisteningchanged]
```swift
@objc optional func onAgentListeningChanged(agentUserId: String, isListening: Bool)
```
智能体倾听状态变化回调。
该回调是对 `onAgentStateChanged` 的细粒度补充,用于监听智能体是否开始或停止倾听用户输入。
#### 参数 [#参数-6]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `isListening` | `Bool` | 智能体当前是否处于倾听状态。 |
## onAgentThinkingChanged [#onagentthinkingchanged]
```swift
@objc optional func onAgentThinkingChanged(agentUserId: String, isThinking: Bool)
```
智能体思考状态变化回调。
该回调是对 `onAgentStateChanged` 的细粒度补充,用于监听智能体是否开始或停止处理请求。
#### 参数 [#参数-7]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `isThinking` | `Bool` | 智能体当前是否处于思考状态。 |
## onAgentSpeakingChanged [#onagentspeakingchanged]
```swift
@objc optional func onAgentSpeakingChanged(agentUserId: String, isSpeaking: Bool)
```
智能体说话状态变化回调。
该回调是对 `onAgentStateChanged` 的细粒度补充,用于监听智能体是否开始或停止播报语音。
#### 参数 [#参数-8]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `isSpeaking` | `Bool` | 智能体当前是否处于说话状态。 |
## onAgentInterrupted [#onagentinterrupted]
```swift
@objc func onAgentInterrupted(agentUserId: String, event: InterruptEvent)
```
中断事件回调。
:::warning[注意]
该回调不一定与智能体的状态同步,因此不建议在该回调中处理核心业务逻辑。
:::
#### 参数 [#参数-9]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `event` | `InterruptEvent` | 中断事件,包含轮次 ID 和时间戳,详见 [`InterruptEvent`](/zh-CN/api-reference/conversational-ai/ios/struct#interruptevent)。 |
## onAgentMetrics [#onagentmetrics]
```swift
@objc func onAgentMetrics(agentUserId: String, metrics: Metric)
```
性能指标可用时触发的回调。
该回调提供性能数据,例如 LLM 推理延迟和 TTS 语音合成延迟,用于监测系统性能。
:::warning[注意]
该回调不一定与智能体的状态同步,因此不建议在该回调中处理核心业务逻辑。
:::
#### 参数 [#参数-10]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `metrics` | `Metric` | 性能指标,包含类型、数值和时间戳。详见 [`Metric`](/zh-CN/api-reference/conversational-ai/ios/struct#metric)。 |
## onAgentError [#onagenterror]
```swift
@objc func onAgentError(agentUserId: String, error: ModuleError)
```
AI 模块发生错误时的回调。
当模块组件(如 LLM、TTS 等)发生错误时,会调用该回调。可用于错误监控、日志记录以及实现服务降级策略。
:::warning[注意]
该回调不一定与智能体的状态同步,因此不建议在该回调中处理核心业务逻辑。
:::
#### 参数 [#参数-11]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `error` | `ModuleError` | 模块错误,包含类型、错误码、错误信息和时间戳。详见 [`ModuleError`](/zh-CN/api-reference/conversational-ai/ios/struct#moduleerror)。 |
## onTranscriptUpdated [#ontranscriptupdated]
```swift
@objc func onTranscriptUpdated(agentUserId: String, transcript: Transcript)
```
转写内容更新回调。
该回调在会话中的语音转写内容发生更新时触发。
#### 参数 [#参数-12]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体的 RTM 用户 ID。 |
| `transcript` | `Transcript` | 转写数据,包含文本内容、状态和元数据。详见 [`Transcript`](/zh-CN/api-reference/conversational-ai/ios/struct#transcript)。 |