> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/convaimanager-api.md). # ConvaiManager API `ConvaiManager` is the primary scripting entry point for the Convai Unity SDK. It initializes the runtime, manages room connections, owns the `Events`, `Audio`, and `Transcripts` facades, and grants access to lower-level services through typed accessors. Every scripted interaction begins here. **Access:** `ConvaiManager.ActiveManager` (singleton) ```csharp var manager = ConvaiManager.ActiveManager; if (manager == null) { Debug.LogError("ConvaiManager not found in scene. Add it via Convai → Create Manager."); return; } ``` {% hint style="warning" %} `ActiveManager` returns `null` if no `ConvaiManager` exists in the scene or if it has not yet bootstrapped. Always null-check before use, especially in components that may `OnEnable` before the manager initializes. {% endhint %} *** ### State properties | Property | Type | Description | | ---------------- | ------ | --------------------------------------------------------------------------------------- | | `IsBootstrapped` | `bool` | Static. True when the runtime has completed initial bootstrap — safe to access facades. | | `IsInitialized` | `bool` | True when bootstrap is complete AND the event hub is available. | | `IsConnected` | `bool` | True when the room session is in `Connected` state. | *** ### Facade accessors | Property | Type | Reference | | ------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Events` | `ConvaiEvents` | [Session Events](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/session-events.md), [Character Events](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/character-events.md) | | `Audio` | `ConvaiAudio` | [Audio API](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/audio-api.md) | | `Transcripts` | `ConvaiTranscripts` | [Transcript API](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/transcript-api.md) | *** ### Ownership properties | Property | Type | Description | | ----------------------------- | -------------------------------- | --------------------------------------------------------------------- | | `Characters` | `IReadOnlyList` | All `ConvaiCharacter` instances currently owned by this manager | | `Player` | `ConvaiPlayer` | The `ConvaiPlayer` instance owned by this manager | | `ActiveConversationCharacter` | `ConvaiCharacter` | The character currently set as the conversation target; may be `null` | | `ConversationMode` | `ConvaiManagerConversationMode` | The configured conversation mode for this manager | | `ActiveConversationInputMode` | `ConversationInputMode` | The runtime conversation input mode currently in effect | | `PushToTalkKey` | `KeyCode` | The key code used for push-to-talk, when mode is `PushToTalk` | #### `ConvaiManagerConversationMode` enum | Value | Description | | --------------------- | --------------------------------------------------------------------------------- | | `UseRoomDefaults` (0) | Uses the conversation input mode configured in `TurnTakingOptions` on the manager | | `HandsFree` (1) | Sets hands-free (LocalAudio) mode, overriding room defaults | | `PushToTalk` (2) | Sets push-to-talk mode, overriding room defaults | *** ### Room operations #### `ConnectAsync` ```csharp // Simple connect — uses scene configuration IConvaiOperation ConnectAsync(CancellationToken ct = default) // Connect with runtime overrides IConvaiOperation ConnectAsync(RoomSessionConnectOptions options, CancellationToken ct = default) ``` Returns a `RoomSession` on success. See [Operation & Stream Types](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/operation-and-stream-types.md) and [Async Patterns](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/async-patterns.md) for consumption patterns. **`RoomSessionConnectOptions` fields** Pass this to the second overload to override runtime behavior at connect time. | Field | Type | Description | | --------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `TurnTaking` | `TurnTakingOptions` | Override the turn-taking configuration for this session. See [Turn-taking modes](/api-docs/plugins-and-integrations/convai-unity-sdk/core-concepts/turn-taking-modes.md) for the full field reference. | | `EndUserId` | `string` | Override the end-user ID for this session (used by Long-Term Memory) | | `EndUserMetadata` | `IReadOnlyDictionary` | Additional metadata for the end user | | `ActionConfigOverride` | `ConvaiActionConfig` | Override the action configuration for this session | | `ActionDefinitionsOverride` | `List` | Override the action definitions registered for this session | ```csharp var options = new RoomSessionConnectOptions { EndUserId = currentUser.Id, EndUserMetadata = new Dictionary { ["department"] = "Engineering", ["cohort"] = "2025-Q2" } }; var result = await manager.ConnectAsync(options, destroyCancellationToken); if (!result.IsSuccessful) Debug.LogError($"Connect failed: {result.Error.Message}"); ``` #### `DisconnectAsync` ```csharp IConvaiOperation DisconnectAsync(CancellationToken ct = default) ``` Gracefully disconnects the room session. Resolves when the session reaches `Disconnected`. *** ### Conversation control | Method | Returns | Description | | ------------------------------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------- | | `SetConversationInputModeAsync(ConversationInputMode mode, CancellationToken ct = default)` | `IConvaiOperation` | Switches the room's conversation input mode at runtime | | `StartListening()` | `void` | Starts microphone capture. Shortcut for `Audio.StartListeningAsync()` with default device. | | `ToggleMicMute()` | `bool` | Toggles microphone mute. Returns the new mute state. | | `EnableAudioAndStartListening()` | `void` | Calls `Audio.EnableAudioPlayback()` then starts listening. Required on WebGL before any audio interaction. | *** ### Direct C# events `ConvaiManager` exposes three direct C# events in addition to the typed hub accessible via `Events`. Subscribe to these when you need lightweight session state notification without the full hub or relay setup. | Event | Signature | Fires When | | ---------------- | ---------------------- | ------------------------------ | | `OnConnected` | `Action` | Session reaches `Connected` | | `OnDisconnected` | `Action` | Session reaches `Disconnected` | | `OnError` | `Action` | Session encounters an error | {% hint style="info" %} For richer session state data (transition context, participant changes, idle warnings), use `ConvaiSessionEventRelay` or `ConvaiManager.ActiveManager.Events`. The direct events above are intentionally minimal — connection and error only. {% endhint %} *** ### Ownership management Use these methods to control which characters and player the manager owns, and which character is the active conversation target. | Method | Description | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `SetExplicitConversationTarget(ConvaiCharacter character)` | Sets the active conversation target character. Pass `null` to clear. | | `SetExplicitPlayer(ConvaiPlayer player)` | Assigns a specific `ConvaiPlayer` instance as the managed player | | `SetExplicitCharacters(IEnumerable characters)` | Replaces the managed character list with the provided set | | `RefreshReferences()` | Rescans the scene for `ConvaiCharacter` and `ConvaiPlayer` instances to rebuild the managed set | *** ### Service accessor pattern For advanced scenarios that require direct access to internal services, `ConvaiManager` exposes 12 typed `TryGet*` accessors. Each returns `true` and sets the `out` parameter on success, or returns `false` if the service is unavailable. {% hint style="info" %} Prefer the `Events`, `Audio`, and `Transcripts` facade properties for common tasks. The `TryGet*` accessors are intended for advanced integrations and custom tooling. {% endhint %} ```csharp if (manager.TryGetMicrophoneDeviceService(out var micService)) { var devices = micService.GetAvailableDevices(); // populate device picker UI } ``` | Method | Service Type | Common Use Case | | ------------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------- | | `TryGetEventHub(out IEventHub)` | `IEventHub` | Raw event bus access via `ConvaiEvents.Raw`; advanced subscriptions | | `TryGetRoomConnectionService(out IConvaiRoomConnectionService)` | `IConvaiRoomConnectionService` | Low-level connection lifecycle control | | `TryGetRoomAudioService(out IConvaiRoomAudioService)` | `IConvaiRoomAudioService` | Direct audio service access (bypasses `ConvaiAudio` facade) | | `TryGetAgentRegistry(out IAgentRegistry)` | `IAgentRegistry` | Query registered characters and players | | `TryGetSettingsPanelController(out IConvaiSettingsPanelController)` | `IConvaiSettingsPanelController` | Programmatically open/close the settings panel | | `TryGetRuntimeSettingsService(out IConvaiRuntimeSettingsService)` | `IConvaiRuntimeSettingsService` | Read and write runtime settings (audio volume, mic device, etc.) | | `TryGetMicrophoneDeviceService(out IMicrophoneDeviceService)` | `IMicrophoneDeviceService` | Enumerate available microphone devices; build device picker UI | | `TryGetPermissionService(out IConvaiPermissionService)` | `IConvaiPermissionService` | Request platform microphone permissions (Android, iOS) | | `TryGetNotificationService(out IConvaiNotificationService)` | `IConvaiNotificationService` | Trigger SDK notifications from your own scripts | | `TryGetPlayerInputService(out IPlayerInputService)` | `IPlayerInputService` | Access player input state and text message routing | | `TryGetVisibleCharacterService(out IVisibleCharacterService)` | `IVisibleCharacterService` | Query which characters are visible in the camera frustum | | `TryGetTransportProvider(out ITransportProvider)` | `ITransportProvider` | Access the transport layer for diagnostic or custom transport scenarios | *** ### SDK version The `ConvaiSDK` static class exposes the SDK version for conditional feature checks. ```csharp using Convai.Application; Debug.Log($"Convai SDK {ConvaiSDK.Version}"); // e.g. "4.2.0" if (ConvaiSDK.Version >= new System.Version(4, 2, 0)) { // Use a feature introduced in 4.2 } ``` *** ### Usage examples #### Example 1 — Connect on scene load with cancellation An industrial safety simulation connects to Convai when the scene loads, tied to the component's lifetime via `destroyCancellationToken` so the connect operation cancels cleanly if the scene unloads mid-attempt. {% code title="SceneConnector.cs" %} ```csharp 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) { /* scene unloaded */ } } } ``` {% endcode %} #### Example 2 — Swap conversation target on trigger zone entry A corporate onboarding simulation has multiple AI advisors in a room. When a learner walks into an advisor's zone, that advisor becomes the active conversation target. {% code title="AdvisorZone.cs" %} ```csharp 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?.SetExplicitConversationTarget(_advisor); } private void OnTriggerExit(Collider other) { if (!other.CompareTag("Player")) return; ConvaiManager.ActiveManager?.SetExplicitConversationTarget(null); } } ``` {% endcode %} #### Example 3 — Microphone device picker UI An interactive experience lets users choose their preferred microphone before a session starts, using `IMicrophoneDeviceService` to enumerate available devices. {% code title="MicrophonePicker.cs" %} ```csharp 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()); } } ``` {% endcode %} *** ### Troubleshooting | Symptom | Likely Cause | Fix | | ----------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `ActiveManager` returns `null` at runtime | `ConvaiManager` not in scene, or accessed before bootstrap completes | Add via **Convai → Create Manager**; null-check before use; subscribe to `OnConnected` instead of reading state in `Awake` or `OnEnable` | | `TryGet*` returns `false` | Service unavailable or manager not fully bootstrapped | Check `IsBootstrapped` before calling; call after `OnConnected` fires | | `ConnectAsync` stays `Running` indefinitely | Invalid API key, network unreachable, or `ConvaiSettings` asset missing | Verify API key in **Convai → Settings**; use a timeout `CancellationToken` to surface the failure | | `RefreshReferences` does not find a dynamically spawned character | Characters instantiated after scene load are not auto-discovered | Call `RefreshReferences()` after instantiation, or use `SetExplicitCharacters()` to register them directly | *** ### Next steps For audio and microphone scripting, see [Audio API](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/audio-api.md). For connection state and error events in C#, see [Session Events](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/session-events.md). For async operation consumption patterns, see [Async Patterns](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/async-patterns.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/convaimanager-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.