展示用户和智能体状态

在与智能体进行实时语音通话时，可能需要在客户端界面上实时展示智能体实例说话和用户说话的状态变化以提升用户体验。您可以通过监听服务端回调的相应事件来获取这些状态。

状态消息包括以下类型：

智能体实例说话状态事件：开始说话，说话结束。
用户说话状态事件：开始说话，说话结束。

快速实现

监听服务端回调

请参考接收回调文档开发好用于接收 AI Agent 事件通知的回调，并提供地址联系 ZEGO 技术支持进行配置。

说明

要接收用户和智能体状态的回调结果，请在创建智能体实例时，配置相应的 CallbackConfig.UserSpeakAction 和 CallbackConfig.AgentSpeakAction 参数为 1：

回调内容示例如下：

智能体说话状态回调

用户说话状态回调

{
    "AppId": 1234567,
    "AgentInstanceId": "1912124734317838336",
    "Data": {
        "Action": "SPEAK_BEGIN",// SPEAK_BEGIN: 开始说话 SPEAK_END: 说话结束
    },
    "Event": "AgentSpeakAction",
    "Nonce": "7450395512627324902",
    "Signature": "fd9c1ce54e85bd92f48b0a805e82a52b0c0c6445",
    "Timestamp": 1745502313000,
    "AgentUserId": "123456789",
    "RoomId": "123456789",
    "Sequence": 123456789,
}

Copied!

{
    "AppId": 1234567,
    "AgentInstanceId": "1912124734317838336",
    "Data": {
        "Action": "SPEAK_BEGIN",// SPEAK_BEGIN: 开始说话 SPEAK_END: 说话结束
    },
    "Event": "UserSpeakAction",
    "Nonce": "7450395512627324902",
    "Signature": "fd9c1ce54e85bd92f48b0a805e82a52b0c0c6445",
    "Timestamp": 1745502313000,
    "AgentUserId": "123456789",
    "RoomId": "123456789",
    "Sequence": 123456789,
}

Copied!

如何通知客户端并展示状态

当您通过服务端回调接收到智能体实例或用户的说话状态事件后，您可以将这些状态信息通知到客户端，以便客户端可以实时展示状态变化。以下是两种常用的通知方式：

使用自有信令通道

如果您的应用已经有自己的信令通道，如 WebSocket 或即时通讯系统，您可以：

在服务端接收到状态事件回调后，通过您的信令通道将状态信息转发给相关客户端。
与客户端约定好消息格式，客户端根据接收到的状态信息更新 UI 界面（如显示说话指示器、动画等）。

这种方式的优点是可以完全控制消息格式和传输逻辑，适合已有成熟信令系统的应用。

借用 ZEGO RTC 房间消息通道，发送自定义消息

如果您没有自己的业务信令通道，可以借用 ZEGO RTC 提供的房间消息功能：

在服务端接收到状态事件回调后，调用 ZEGO RTC Server API 发送自定义消息
与客户端约定好消息格式，客户端通过 ZEGO RTC SDK 监听自定义消息，接收状态变化通知更新 UI 界面（如显示说话指示器、动画等）

这种方式的优点是无需额外搭建信令系统，可以直接利用 ZEGO 提供的基础设施。但是这种方式的缺点是房间消息不保证完全可靠，且有发送频率限制，不适用于对消息可靠性要求较高的场景。

实现示例如下：

服务端

客户端