ConvaiManager API

场景管理器组件的每个公共成员，涵盖连接控制、外观访问、玩家正在与谁交谈以及服务发现。

ConvaiManager 是 Convai Unity SDK 的主要脚本入口点。它会初始化运行时，管理房间连接，并拥有 事件, 音频以及 转录 门面，并通过类型化访问器提供对底层服务的访问。每一次脚本交互都从这里开始。

访问： ConvaiManager.ActiveManager (单例)

var manager = ConvaiManager.ActiveManager;
if (manager == null)
{
    Debug.LogError("场景中未找到 ConvaiManager。请通过 GameObject > Convai > Setup Required Components 将其添加到场景中。");
    return;
}

ActiveManager 返回 null 如果没有 ConvaiManager 存在于场景中，或者尚未完成引导。使用前始终先判空，尤其是在可能 OnEnable 在管理器初始化之前。

---

状态属性

属性	类型	说明
IsBootstrapped	布尔值	静态。当运行时完成初始引导时为 True——可以安全访问门面。
IsInitialized	布尔值	当引导完成且事件中心可用时为 True。
IsConnected	布尔值	当房间会话处于 已连接 状态时为 True。

---

门面访问器

属性	类型	引用
事件	ConvaiEvents	会话事件, 角色事件
音频	ConvaiAudio	音频 API
转录	ConvaiTranscripts	转录 API

---

所有权属性

属性	类型	说明
角色	IReadOnlyList<ConvaiCharacter>	全部 ConvaiCharacter 当前由此管理器拥有的实例
玩家	ConvaiPlayer	“ ConvaiPlayer 由此管理器拥有的实例
ActiveConversationCharacter	ConvaiCharacter	当前设置为对话目标的角色；可能 null
ConversationMode	ConvaiManagerConversationMode	此管理器配置的对话模式
ActiveConversationInputMode	ConversationInputMode	当前生效的运行时对话输入模式
PushToTalkKey	KeyCode	用于按住说话的按键代码，当模式为 PushToTalk

ConvaiManagerConversationMode 枚举

值	说明
UseRoomDefaults (0)	使用配置在 TurnTakingOptions 管理器上
HandsFree (1)	设置免持（LocalAudio）模式，覆盖房间默认值
PushToTalk (2)	设置按住说话模式，覆盖房间默认值

---

房间操作

ConnectAsync

// 简单连接——使用场景配置
IConvaiOperation<RoomSession> ConnectAsync(CancellationToken ct = default)

// 使用运行时覆盖进行连接
IConvaiOperation<RoomSession> ConnectAsync(RoomSessionConnectOptions options, CancellationToken ct = default)

返回一个 RoomSession 成功时返回。参见 操作与流类型 和 异步模式 以了解使用模式。

RoomSessionConnectOptions 字段

将其传递给第二个重载，以便在连接时覆盖运行时行为。

字段	类型	说明
TurnTaking	TurnTakingOptions	覆盖此会话的轮流发言配置。参见 轮流发言模式 以查看完整字段参考。
EndUserId	字符串	覆盖此会话的终端用户 ID（供长期记忆使用）
角色会话 ID	字符串	限定于此显式终端用户连接请求的可选会话 ID。在存在终端用户 ID 时，优先使用它，而不是角色自己的 ConvaiCharacter.CharacterSessionId 字段。
EndUserMetadata	IReadOnlyDictionary<string, object>	终端用户的附加元数据
ActionConfigOverride	ConvaiActionConfig	覆盖此会话的动作配置
ActionDefinitionsOverride	List<ConvaiActionDefinition>	覆盖为此会话注册的动作定义
SharedSessionKey	字符串	可选的共享会话密钥，用于将多人参与者分组到同一房间。参见 连接 API 参考.
房间会话 ID	字符串	加入现有房间时使用的持久多角色房间标识符。请通过 MultiCharacterJoinOptions 进行正常使用，而不是直接设置。
JoinExistingMultiCharacterRoom	布尔值	选择一种无需拓扑的人类加入方式，而不是构建并发送名册。
MaxNumParticipants	整数	共享会话的可选最大参与者数量。

var options = new RoomSessionConnectOptions
{
    EndUserId = currentUser.Id,
    EndUserMetadata = new Dictionary<string, object>
    {
        ["department"] = "Engineering",
        ["cohort"]     = "2025-Q2"
    }
};

var result = await manager.ConnectAsync(options, destroyCancellationToken);
if (!result.IsSuccessful)
    Debug.LogError($"连接失败：{result.Error.Message}");

DisconnectAsync

IConvaiOperation<Unit> DisconnectAsync(CancellationToken ct = default)

优雅地断开房间会话。会在会话到达 已断开连接.

---

对话控制

方法	返回值	说明
SetConversationInputModeAsync(ConversationInputMode mode, CancellationToken ct = default)	IConvaiOperation<Unit>	在运行时切换房间的对话输入模式
StartListening()	void	开始麦克风采集。是以下调用的快捷方式： Audio.StartListeningAsync() ，使用默认设备。
ToggleMicMute()	布尔值	切换麦克风静音。返回新的静音状态。
EnableAudioAndStartListening()	void	调用 Audio.EnableAudioPlayback() 然后开始监听。在 WebGL 中，任何音频交互之前都需要先执行此操作。

---

直接 C# 事件

ConvaiManager 除可通过 事件访问的类型化 hub 外，还公开三个直接的 C# 事件。当你需要轻量级会话状态通知，而不需要完整的 hub 或中继设置时，请订阅这些事件。

事件	签名	触发时机
OnConnected	Action	会话达到 已连接
OnDisconnected	Action	会话达到 已断开连接
OnError	Action<SessionError>	会话遇到错误

如需更丰富的会话状态数据（过渡上下文、参与者变更、空闲警告），请使用 ConvaiSessionEventRelay 或 ConvaiManager.ActiveManager.Events。上面的直接事件刻意保持精简——仅包含连接和错误。

---

所有权管理

使用这些方法和属性来控制管理器拥有哪些角色和玩家、哪些角色加入下一次房间连接，以及房间以哪个角色开启。

成员	说明
SetInitialCharacter(ConvaiCharacter character)	在房间连接时选择哪个角色先发言。这属于设置，而不是实时引导——它决定对话从哪里开始；在已连接的房间中更改它会排队触发重新连接，而不是移动对话。保持未设置是正常的：场景顺序中的第一个角色会获得第一轮发言。若要在实时房间中切换对话目标，请使用 TalkTo.
InitialCharacter	ConvaiCharacter的读取部分 SetInitialCharacter. null 在没有明确选择任何内容时。
TalkTo(ConvaiCharacter character)	将对话指向一个实时、多角色房间中的某个角色。任何时候调用都安全；当房间不是多角色房间或该角色不在其中时不会执行任何操作。参见 对话目标定位.
AddressedCharacter	ConvaiCharacter。玩家当前正在对话的角色，在房间创建前后都会解析到它。将聊天字段标签绑定到它，绝不要绑定到玩家碰巧正在看的对象。
ConversationAvailability	ConvaiConversationAvailability。玩家是否可以与 AddressedCharacter 当前。取值： NoCharacter, Offline, Connecting, Preparing, 就绪, Answering, Unavailable.
ConversationAvailability.CanAcceptPlayerInput()	对……的扩展方法 ConvaiConversationAvailability。当没有可测量对象时返回 是 当值为 就绪 或 Answering ——这是唯一两个接受消息的状态。聊天字段和麦克风按钮应以此为准，而不是以 IsConnected.
ConversationTargeting	ConversationTargetingOptions。用于自动对话目标定位的调优（模式、范围、视角、切换余量、切换延迟）。绝不要 null.
SetCharactersToConnect(IEnumerable<ConvaiCharacter> characters)	选择下一次房间连接中包含的确切受管理角色集合，并替换任何先前的选择。传入空集合会有意让下一次连接没有有效的角色名单。更改仅应用于下一次连接，而不是当前连接。
CharactersToConnect	IReadOnlyList<ConvaiCharacter>。由 SetCharactersToConnect设置的显式房间选择集合，或者在包含所有活动角色时为空。该选择是一个精确集合，而不是可追加的列表——在调用之前先阅读此说明 SetCharactersToConnect 如果你的意思是“以及这个”。
UseAllCharactersForConnection()	恢复默认行为，即将每个已拥有的、处于活动状态的场景角色都包含到下一次房间连接中。
SetExplicitPlayer(ConvaiPlayer player)	指定一个 ConvaiPlayer 实例作为受管理玩家
SetExplicitCharacters(IEnumerable<ConvaiCharacter> characters)	用提供的集合替换受管理的角色列表
RefreshReferences()	重新扫描场景中的 ConvaiCharacter 和 ConvaiPlayer 实例，以重建受管理集合

运行时生成的角色

在场景加载后实例化的角色，在 Instantiate 返回时也不行。管理器必须先接管其所有权并注入其服务，而这会在之后的某一帧发生。 ConvaiCharacter.IsInjected 会在该过程完成时报告，而在此之前，该角色的对话和音频调用都不会生效。

生成角色后，调用 RefreshReferences() ——或者 SetExplicitCharacters 如果管理器没有自动扫描场景——然后等待 IsInjected 在与其对话之前。

using System;
using System.Threading.Tasks;
using Convai.Runtime.Components;
using UnityEngine;

public static class RuntimeCharacterSpawn
{
    public static async Task<ConvaiCharacter> SpawnAsync(GameObject prefab, Vector3 position)
    {
        ConvaiCharacter character = UnityEngine.Object
            .Instantiate(prefab, position, Quaternion.identity)
            .GetComponent<ConvaiCharacter>();

        ConvaiManager.ActiveManager.RefreshReferences();

        for (int frame = 0; frame < 120; frame++)
        {
            if (character != null && character.IsInjected) return character;
            await Task.Yield();
        }

        throw new InvalidOperationException(
            "运行时角色未被注入。请确保场景中存在一个处于活动状态的 ConvaiManager。");
    }
}

SDK 将此模式作为 RuntimeCharacterSpawner 提供在共享示例中。

---

服务访问器模式

对于需要直接访问内部服务的高级场景， ConvaiManager 公开 12 个类型化的 TryGet* 访问器。每个都会返回 是 并在成功时设置 out 参数，或者返回 否 如果服务不可用，则返回 false。

优先使用 事件, 音频以及 转录 门面属性来完成常见任务。 TryGet* 这些访问器面向高级集成和自定义工具。

if (manager.TryGetMicrophoneDeviceService(out var micService))
{
    var devices = micService.GetAvailableDevices();
    // 填充设备选择器界面
}

方法	服务类型	常见用例
TryGetEventHub(out IEventHub)	IEventHub	通过 ConvaiEvents.Raw进行原始事件总线访问；高级订阅
TryGetRoomConnectionService(out IConvaiRoomConnectionService)	IConvaiRoomConnectionService	底层连接生命周期控制，包括 多角色会话操作
TryGetRoomAudioService(out IConvaiRoomAudioService)	IConvaiRoomAudioService	直接访问音频服务（绕过 ConvaiAudio 门面）
TryGetAgentRegistry(out IAgentRegistry)	IAgentRegistry	查询已注册的角色和玩家
TryGetSettingsPanelController(out IConvaiSettingsPanelController)	IConvaiSettingsPanelController	以编程方式打开/关闭设置面板
TryGetRuntimeSettingsService(out IConvaiRuntimeSettingsService)	IConvaiRuntimeSettingsService	读写运行时设置（音量、麦克风设备等）
TryGetMicrophoneDeviceService(out IMicrophoneDeviceService)	IMicrophoneDeviceService	枚举可用麦克风设备；构建设备选择器界面
TryGetPermissionService(out IConvaiPermissionService)	IConvaiPermissionService	请求平台麦克风权限（Android、iOS）
TryGetNotificationService(out IConvaiNotificationService)	IConvaiNotificationService	从你自己的脚本中触发 SDK 通知
TryGetPlayerInputService(out IPlayerInputService)	IPlayerInputService	访问玩家输入状态和文本消息路由
TryGetVisibleCharacterService(out IVisibleCharacterService)	IVisibleCharacterService	维护由你自己的可见性逻辑通过 AddCharacter/RemoveCharacter添加的角色 ID 集合；由转录界面用于过滤和淡出
TryGetTransportProvider(out ITransportProvider)	ITransportProvider	访问传输层，用于诊断或自定义传输场景

---

SDK 版本

“ ConvaiSDK 静态类公开 SDK 版本，用于条件功能检查。

using Convai.Application;

Debug.Log($"Convai SDK {ConvaiSDK.Version}");

// 将其设置为你的集成所支持的最低 SDK 版本。
const string MinimumSupportedVersion = "4.6.0";

if (ConvaiSDK.Version >= System.Version.Parse(MinimumSupportedVersion))
{
    // 可以安全使用该版本可用的 API
}

---

使用示例

示例 1——在场景加载时带取消连接

一个工业安全模拟在场景加载时连接到 Convai，并通过 destroyCancellationToken 因此，如果场景在尝试中途卸载，连接操作会干净地取消。

SceneConnector.cs

using Convai.Runtime.Core.Async;
using Convai.Runtime.Facades;
using UnityEngine;

public class SceneConnector : MonoBehaviour
{
    private async void Start()
    {
        var manager = ConvaiManager.ActiveManager;
        if (manager == null) return;

        try
        {
            var session = await manager.ConnectAsync(destroyCancellationToken);
            Debug.Log($"Connected. Session: {session.RoomId}");
        }
        catch (ConvaiOperationException ex)
        {
            Debug.LogError($"Connect failed: {ex.Message}");
        }
        catch (System.OperationCanceledException) { /* 场景已卸载 */ }
    }
}

示例 2——在触发区域进入时移动对话

一个企业入职模拟在同一个房间中有多个 AI 顾问。当学习者走进某位顾问的区域时，对话会切换到该顾问，使用 TalkTo.

AdvisorZone.cs

using Convai.Runtime.Components;
using Convai.Runtime.Facades;
using UnityEngine;

public class AdvisorZone : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _advisor;

    private void OnTriggerEnter(Collider other)
    {
        if (!other.CompareTag("Player")) return;
        ConvaiManager.ActiveManager?.TalkTo(_advisor);
    }
}

示例 3——麦克风设备选择器 UI

一个交互式体验允许用户在会话开始前选择他们偏好的麦克风，使用 IMicrophoneDeviceService 来枚举可用设备。

MicrophonePicker.cs

using Convai.Runtime.Facades;
using System.Linq;
using TMPro;
using UnityEngine;

public class MicrophonePicker : MonoBehaviour
{
    [SerializeField] private TMP_Dropdown _deviceDropdown;

    private void Start()
    {
        var manager = ConvaiManager.ActiveManager;
        if (manager == null || !manager.TryGetMicrophoneDeviceService(out var micService))
            return;

        var devices = micService.GetAvailableDevices();
        _deviceDropdown.ClearOptions();
        _deviceDropdown.AddOptions(devices.Select(d => d.Name).ToList());
    }
}

---

故障排查

症状	可能原因	修复方法
ActiveManager 返回 null 在运行时	ConvaiManager 不在场景中，或者在引导完成之前被访问	通过……添加 GameObject > Convai > Setup Required Components；使用前先判空；订阅 OnConnected 而不是在……中读取状态 Awake 或 OnEnable
TryGet* 返回 否	服务不可用，或者管理器尚未完全引导	检查 IsBootstrapped 在调用前；在……之后调用 OnConnected 触发
ConnectAsync 保持 运行中 无限期	API 密钥无效、网络不可达，或者 ConvaiSettings 资源缺失	在……中验证 API 密钥 Convai → Settings；使用超时 CancellationToken 以暴露失败
RefreshReferences 找不到动态生成的角色	场景加载后实例化的角色不会被自动发现	调用 RefreshReferences() 在实例化后，或者使用 SetExplicitCharacters() 直接注册它们

---

下一步

有关音频和麦克风脚本，请参见 音频 API。有关 C# 中的连接状态和错误事件，请参见 会话事件。有关异步操作的使用模式，请参见 异步模式.