Character Versioning section. There is no snapshot here yet.
Let's create our very first snapshot.
We provide a name and a small description.
The snapshot appears in the list
We will be restoring the data from the very first snapshot.
Let's directly restore the data in the snapshot to the Current Snapshot
Click on the 3-dots beside the snapshot to see all the options.
| Model | Model Code | Flagship |
|---|---|---|
| GPT Realtime 1.5 (beta) | gpt-realtime-1.5 | false |
| GPT Realtime Mini (beta) | gpt-realtime-mini | false |
| Model | Model Code | Flagship |
|---|---|---|
| Gemini 2.5 Flash Live (beta) | gemini-2.5-flash-live | false |
| Gemma 4 31B Fast (beta) | realtime-gemma-4-31b-it | false |
| Gemma 4 26B A4B Fast (beta) | realtime-gemma-4-26b-a4b-it | false |
| Model | Model Code | Flagship |
|---|---|---|
| GPT-5.4 | gpt-5.4 | false |
| GPT-5.x (latest) | gpt-5.x | true |
| GPT-OSS-120B (beta) | gpt-oss-120b | false |
| GPT-5.1 (beta) | gpt-5.1 | false |
| GPT-4.1 | gpt-4.1 | false |
| GPT-5.4-nano | gpt-5.4-nano | false |
| GPT-5.x-nano (latest) | gpt-5.x-nano | true |
| GPT-5.4-mini | gpt-5.4-mini | false |
| GPT-5.x-mini (latest) | gpt-5.x-mini | true |
| GPT-4.1-mini | gpt-4.1-mini | false |
| GPT-5.3 Instant | gpt-5.3-instant | false |
| GPT-4o | gpt-4o | false |
| GPT-4.1-nano | gpt-4.1-nano | false |
| GPT-4o-mini | gpt-4o-mini | false |
| Model | Model Code | Flagship |
|---|---|---|
| Claude 4.5 Sonnet (beta) | claude-4-5-sonnet | false |
| Claude 4.5 Haiku (beta) | claude-4-5-haiku | false |
| Claude Sonnet (latest) | claude-sonnet | true |
| Claude Haiku (latest) | claude-haiku | true |
| Model | Model Code | Flagship |
|---|---|---|
| Gemini 3.5 Flash | gemini-3.5-flash | false |
| Gemini Flash (latest) | gemini-flash | true |
| Gemini 3.1 Flash Lite | gemini-3.1-flash-lite | false |
| Gemini Flash Lite (latest) | gemini-flash-lite | true |
| Gemini 2.5 Flash | gemini-2.5-flash | false |
| Gemini 2.5 Flash Lite | gemini-2.5-flash-lite | false |
space.vars.platform\_fee\_credits credits. Speech, session duration, memory, knowledge retrieval, and other enabled services add their own usage, and Convai rounds each turn's total up to the next whole credit. See [How Convai credits work](/api-docs/credits-and-billing/convai-credits/how-convai-credits-work).
| Model | Model Code | Flagship |
|---|---|---|
| Qwen3.6 27B (beta) | qwen3.6-27b | false |
| Qwen3.6 35B A3B (beta) | qwen3.6-35b-a3b | false |
| Model | Model Code | Flagship |
|---|---|---|
| Llama 4 Maverick (beta) | llama-4-maverick | false |
| Llama 4 Scout (beta) | llama-4-scout | false |
| Llama3 70B | llama3-70b | false |
| Model | Model Code | Flagship |
|---|---|---|
| Grok 4.3 | grok-4.3 | false |
Prepare and save an Actions Contract while Agentic Actions is off. The saved text is not added to the model prompt until you enable the feature for a new connection.
The selector contains three embodied examples and three browser-agent examples.
Adding a template preserves the existing contract and appends the full example. It does not enable Agentic Actions or save automatically.
The enabled switch activates saved action instructions for new connections. The parsed-action row confirms recognition and delivery, not client execution.
With raw display off, chat shows the normal response and the parsed action status without exposing provider output.
With raw display on, provider-visible JSON appears for inspection and the parsed action remains separate. Neither row proves that a client executed the action.
HTTP headers: name/value pairs sent with every request, e.g. Authorization: Bearer \.
OAuth: sign in to the provider instead of entering a key.
| Open My Experiences Reach the hub where chat experiences and 3D experiences are both created and reopened. | Open My Experiences |
| What you need to use Chat Experiences The account and character requirements, and what to do if the controls are missing. | What you need to use Chat Experiences |
| Create a chat experience Name the room, pick its type, write its purpose, and read the briefing before it is fixed. | Create a chat experience |
| Add characters to the room Seat characters from your workspaces or by character ID, and watch each one join and be briefed. | Add characters to the room |
| Send your first message Write to the room, address a character so that it answers, and read what the thread reports. | Send your first message |
| Manage your chat experiences Find, rename, duplicate, and delete the chat experiences on your account. | Manage your chat experiences |
| Share files with the room What reaches the characters when you attach a file to a message, and what the room keeps afterwards. | Share files with the room |
space.vars.dashboard\_url.
* **My Experiences** available in the left sidebar of the dashboard. See [What you need to use Chat Experiences](/api-docs/no-code-experiences/chat-experiences/prerequisites).
### Open the My Experiences page
{% stepper %}
{% step %}
#### Sign in to the dashboard
Go to space.vars.dashboard\_url and sign in to your Convai account.
{% endstep %}
{% step %}
#### Select My Experiences
In the left sidebar, select **My Experiences**. On a narrow screen the same entry reads **Experiences**.
The page header reads **My Experiences** with the number of experiences on the account after it, for example **My Experiences (7)**.
{% endstep %}
{% endstepper %}
### Choose a chat experience or a 3D experience
**My Experiences** carries one button for each kind of experience, at the top right of the page:
| Button | What it creates | What opens |
| ---------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Create a 3D Experience** | Your characters placed in a scene or a simulation | The **Start a new Experience** dialog, where you pick a scene |
| **Create a Chat Experience** | A text room built from your characters | The **Create a chat experience** dialog, where you name the experience, pick a room type, and write the purpose |
Below the buttons, the page lists each kind in its own section: **Chat experiences** and **3D experiences**. Anything you have already made is listed there rather than created again—a chat experience card opens a new room from that experience's brief, and a 3D experience card opens that experience for editing.
{% hint style="info" %}
If **Create a Chat Experience** is not on the page, see [What you need to use Chat Experiences](/api-docs/no-code-experiences/chat-experiences/prerequisites).
{% endhint %}
### Next steps
Read what a chat experience is and what a room does and does not do before creating one.
{% content-ref url="/pages/fr2HihLferHR6m3TZw7f" %}
[Chat Experiences](/api-docs/no-code-experiences/chat-experiences)
{% endcontent-ref %}
To build a 3D experience instead, continue with the Convai Sim guide, which covers choosing a scene and placing your characters in it.
{% content-ref url="/pages/wKIgxvLa1ZFp5chDyXOA" %}
[Creating Your AI Simulation with Convai Sim](/api-docs/no-code-experiences/convai-sim-experiences/creating-your-ai-simulation-with-convai-sim)
{% endcontent-ref %}
# What you need to use Chat Experiences
What a Convai account needs before you can build a chat experience, which characters you can add to a room, and what to do if the controls are missing.
Creating and running a chat experience takes a Convai account, at least one character, and the Chat Experiences controls on **My Experiences**.
### Account requirements
| Requirement | Detail |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Convai account | Signed in at space.vars.dashboard\_url. |
| Dashboard access | **My Experiences** present in the left sidebar. Chat experiences are created and reopened from that page, and there is no other entry point. |
| At least one character | One of your own characters, or one someone has shared with you by ID. A room needs at least one character before you can send a message to it. |
### Characters you can add to a room
A room is the text conversation that opens when you start a chat experience. You add characters from inside it, in the **Add characters to the room** dialog. It has two tabs, and each lists a different set of characters:
| Tab | What it lists |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **From my workspaces** | The characters in the workspace you are working in, most recently edited first. The grid shows the eight most recent, and **Show all** expands it to the full list. |
| **By character ID** | Characters you look up by ID. Enter one ID per line to look up several at once. Use this tab for a character someone has shared with you from outside your workspaces. |
A character joins with its own persona and receives the experience's brief on top of it. The brief comes from the room type and the purpose you choose when you create the experience.
### When the Create a Chat Experience button is missing
If **My Experiences** shows neither a **Create a Chat Experience** button nor a **Chat experiences** section, contact | How the room brief is written How the room type and the purpose become one briefing, what a room of one receives instead, and what is trimmed when it runs long. | How the room brief is written |
| Room types reference All six room types, the rules each one sets, and the purpose it fills in for you. | Room types reference |
| Write your own briefing Replace the briefing written for you with your own wording, and put the written-for-you version back. | Write your own briefing |
| Why the brief cannot be changed What is settled at creation, and how to run the same characters against different wording. | Why the brief cannot be changed |
| How a turn works Why the room answers one message at a time, what the turn caption counts, and why a character may say nothing. | How a turn works |
| Choose who replies Set who answers the next message, and tag individual characters when you want only them. | Choose who replies |
| Respond modes reference All five respond modes, what each asks of the characters, and what the thread shows afterwards. | Respond modes reference |
| Add or remove characters mid-conversation Seat a character in a running room, remove one, and work with the controls that freeze during a turn. | Add or remove characters mid-conversation |
| Room controls reference Every control in the top bar and the side panel, and what each one does. | Room controls reference |
| Review a past session Open an experience's history, pick a finished conversation, and read what the transcript records. | Review a past session |
| Export a transcript Download a conversation as a Markdown file, and know what that file holds. | Export a transcript |
| Share a document Attach a PDF, a Word file, or a plain-text file, and read what the chip reports about it. | Share a document |
| Share an image Attach a picture, and understand what the characters are told about it. | Share an image |
| File limits reference The accepted file types, the size and text limits, and what happens at each one. | File limits reference |
| The room will not connect Characters that never finish joining, an experience that will not open, and a character the picker will not add. | The room will not connect |
| You cannot send a message Every reason the message box is locked, in the room's own words, and what clears each one. | You cannot send a message |
| Briefs and transcripts A brief that cannot be edited, an experience that will not be created, and a session that will not open or a transcript that will not download. | Briefs and transcripts |
| File limits reference A file the room will not attach, an attachment taken off a message for length, and text cut short before it reaches the characters. | File limits reference |
space.vars.dashboard\_url and sign in to your Convai account. In the left sidebar, select **My Experiences**.
#### 2. Create a 3D Experience
A 3D experience is a Convai Sim simulation: your characters placed in a scene you can walk around in. On the **My Experiences** page, click **Create a 3D Experience**. The **Start a new Experience** dialog opens.
#### 3. Choose an Environment
Select an environment that fits your use case (e.g., office, museum, sci-fi room). Then click **“Start Experience”** to enter the Convai Sim.
#### 4. Explore the Scene
Once the scene loads:
* Use **WASD keys** to move around.
* Use your **mouse** to look around the environment — just like in a first-person game.
#### 5. Add an Avatar
Click the **top-left icon** to open the avatar menu. Then:
* Click **“Add Avatar”**.
* A hologram will appear — place it at the desired location in the scene.
#### 6. Select Your Character and Avatar
You’ll be prompted to:
* Choose your previously created **Convai character**.
* Select a **Metahuman avatar** to visually represent that character.
#### 7. Deploy the Character
Click **“Deploy Character”** to spawn the avatar into the environment. The avatar will now be active and ready to interact.
#### 8. Add More Avatars (Optional)
Repeat the process to add **multiple characters** into the same scene and create more dynamic simulations.
***
### Next steps
The scene is now running with your character deployed in it. Adjust that avatar’s model, size, and placement in the scene next.
{% content-ref url="/pages/lJ3ep46Kfwn6q0IGsBdC" %}
[Avatar Customization](/api-docs/no-code-experiences/convai-sim-experiences/avatar-customization)
{% endcontent-ref %}
# Avatar Customization
Fine-tune your deployed avatar’s appearance, size, and position within your 3D simulation scene
## **Refine Your Avatar for a Perfect Fit**
Once you've placed your avatar into the scene, it's time to customize its model, pose, and placement to match your simulation's tone and context.
***
## **Customizing Your Avatar**
| Overview What the SDK is, how it is structured, and when to use each module. | Convai Unity SDK overview |
| Compatibility and requirements Unity versions, render pipelines, platform support, and network requirements. | Compatibility and requirements |
| Core concepts Session lifecycle, turn-taking modes, and the SDK event system. | Core concepts |
| Embodiment Gaze, body animation, body language, conversation flow, and emotion modules for character behavior. | Embodiment |
| AI coding assistant Unity MCP integration that lets AI coding agents build Convai scenes from prompts. | AI coding assistant |
| Actions Characters execute structured in-scene commands dispatched by Convai. | Character actions |
| Emotion Map Convai emotion signals to facial blendshapes or Animator parameters. | Emotion |
| Long-term memory Characters remember each player across separate sessions. | Long-term memory |
| Vision Characters see through a Unity camera, webcam, or Meta Quest passthrough. | Vision |
| Dynamic context Inject runtime state and events into character knowledge at any time. | Dynamic context |
| Narrative design Trigger-based story section progression tied to conversation flow. | Narrative design |
| Scene metadata Characters automatically read contextual information about scene objects. | Scene metadata |
| UI and presentation Transcript UI, subtitle modes, notification system, and settings panel. | UI and Presentation |
| Scripting reference Full API reference for session events, character events, and the transcript system. | Scripting reference |
| Platform guides WebGL, Android, iOS, and Meta Quest deployment guides. | Platform guides |
| Advanced topics Custom providers, performance, and SDK extension points. | Customize and extend the SDK |
| Troubleshooting Common failure modes, diagnostic steps, and known issues. | Troubleshooting |
space.vars.unity\_sdk\_version introduces the embodiment family of character-behavior modules: Gaze, Body Animation, Body Language, Conversation Flow, and Emotion. The five modules share one per-character setup and read the same dialogue state, so a character looks, moves, and reacts as one behavior rather than five independent ones. This release also adds an Auth Token authentication mode that resolves a short-lived credential before each connection, so a player build ships without an account API key. The Actions Editor is rebuilt around a curated catalog of 21 built-in actions and provisions an action's executor and its character-side components in a single undoable operation. A new `Convai > Troubleshooter` window reports setup problems per module. The SDK requires Unity space.vars.unity\_min\_version. See [Release notes](/api-docs/plugins-and-integrations/convai-unity-sdk/overview/release-notes) for the complete changelog.
### Next steps
Install the Convai Unity SDK and connect your first AI character using the Getting started section. If you are evaluating the SDK before installing, review [Compatibility and requirements](/api-docs/plugins-and-integrations/convai-unity-sdk/compatibility-and-requirements) to confirm platform and Unity version support.
{% content-ref url="/pages/1d9fa274483952ca377014dd2a4fb49c2f3e80a1" %}
[Getting started](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started)
{% endcontent-ref %}
# Convai Unity SDK overview
Find explanations of what the Convai Unity SDK is, how its four-tier architecture is organized, and what feature modules ship with the package.
The Convai Unity SDK layers voice, structured actions, and long-term memory onto Unity characters. The embodiment modules — Gaze, Body Animation, Body Language, Conversation Flow, and Emotion — drive how a character looks, moves, and reacts while it speaks. The pages in this section explain the SDK fundamentals, system architecture, available features, and current release notes.
| What is the Convai Unity SDK End-to-end voice pipeline, target audience, and what the SDK ships with. | What is the Convai Unity SDK |
| Convai Unity SDK architecture Four-tier framework: Runtime, Room, Agent, and Module layers. | Convai Unity SDK architecture |
| Feature map Find the right feature, tool, or guide for any development goal. | Feature map |
| Release notes Release notes for v space.vars.unity_sdk_version and previous releases. | Release notes |
space.vars.unity\_min\_version |
| Render pipeline | Built-in, URP, or HDRP |
| Platform | Windows, macOS, Linux, Android, iOS, Meta Quest, WebGL |
| Network | Internet connection to Convai |
| API key | Free account at [convai.com](https://www.convai.com/) |
{% hint style="info" %}
The sample scenes use URP. If your project uses the Built-in render pipeline, the samples require minor material reassignment. The SDK itself works with all three pipelines.
{% endhint %}
The Convai Unity SDK is available on the [Unity Asset Store](https://assetstore.unity.com/packages/tools/behavior-ai/npc-ai-engine-dialog-actions-voice-and-lipsync-convai-235621).
For the full platform and Unity version support matrix, see Compatibility and requirements.
{% content-ref url="/pages/ijdGXp5AdxHr05KBoBHM" %}
[Compatibility and requirements](/api-docs/plugins-and-integrations/convai-unity-sdk/compatibility-and-requirements)
{% endcontent-ref %}
### Next steps
Install the SDK and add your first character.
{% content-ref url="/pages/1d9fa274483952ca377014dd2a4fb49c2f3e80a1" %}
[Getting started](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started)
{% endcontent-ref %}
To understand the system architecture before setting up, see the architecture page next.
{% content-ref url="/pages/E0sHZRYpXvCTPJiLrAH4" %}
[Convai Unity SDK architecture](/api-docs/plugins-and-integrations/convai-unity-sdk/overview/convai-unity-sdk-architecture)
{% endcontent-ref %}
# Convai Unity SDK architecture
Understand the Convai Unity SDK four-tier architecture — Runtime, Room, Agent, and Module — and the responsibilities of each tier.
The SDK is organized into four tiers: Runtime, Room, Agent, and Module. As a developer, you interact primarily with the Agent tier (character and player components) and the Module layer (opt-in feature modules). The Runtime and Room tiers handle connection and service bootstrapping with minimal configuration required.
### System diagram
```mermaid
graph TD
subgraph RT["Runtime Tier"]
CM["ConvaiManager\n(composition root, service hub)"]
CS["ConvaiSDK\n(version metadata)"]
end
subgraph RM_TIER["Room Tier"]
RM["ConvaiRoomManager\n(connection · audio · turn-taking)"]
end
subgraph AG["Agent Tier"]
CC["ConvaiCharacter × N\n(session · transcripts · events)"]
CP["ConvaiPlayer\n(identity · text input)"]
end
subgraph ML["Module Layer (opt-in per character)"]
direction LR
LS[LipSync]
EM[Emotion]
VI[Vision]
NA[Narrative]
DA[DialogueAnimation]
FA[FacialAnimation]
GA[Gaze]
AT[Attention]
CF[ConversationFlow]
EB[Embodiment]
end
CM --> RM
RM --> CC
RM --> CP
CC -.->|modules attach to| ML
```
The dashed line from `ConvaiCharacter` to the Module Layer means modules are optional components you add to the same GameObject as the character — not required for basic conversation.
### Runtime tier
The Runtime tier boots when your scene loads and provides services to everything below it.
`ConvaiSDK` is a static class that exposes the SDK version (`ConvaiSDK.Version`). You rarely reference it directly.
`ConvaiManager` is the composition root. It is a singleton (`ConvaiManager.ActiveManager`) marked with `[DefaultExecutionOrder(-1100)]` so it initializes before other scene objects. It owns:
* **Service accessors** — `TryGet` methods for every internal service (microphone, audio, agent registry, notification, settings panel, etc.)
* **High-level facades** — `ConvaiManager.Audio`, `ConvaiManager.Transcripts`, `ConvaiManager.Events` for the most common scripting tasks
* **Connection control** — `ConnectAsync()`, `DisconnectAsync()`, `SetConversationInputModeAsync()`
* **Agent references** — `Characters`, `Player`, `ActiveConversationCharacter`
{% hint style="info" %}
Most integration code only needs `ConvaiManager.ActiveManager` and the character's own events. The `TryGet` service accessors are for advanced use cases where you replace or extend internal services.
{% endhint %}
### Room tier
`ConvaiRoomManager` owns the live connection to Convai. One `ConvaiRoomManager` per scene, managed by `ConvaiManager`.
It is responsible for:
* **Room connection lifecycle** — connecting, disconnecting, reconnecting
* **Microphone capture** — starting and stopping audio input, mute control
* **Turn-taking mode** — hands-free (`ConversationInputMode.HandsFree`) or push-to-talk (`ConversationInputMode.PushToTalk`)
* **Dynamic context transport** — sending state updates and events to Convai at runtime
* **Audio playback coordination** — enabling remote character audio, WebGL user-gesture handling
`ConvaiRoomManager` exposes coordinators for diagnostics, audio, ownership, and connection management. These are accessible via `ConvaiManager.ActiveManager.TryGetRoomConnectionService()` for advanced scripting.
### Agent tier
The Agent tier contains the components you place on scene GameObjects.
#### ConvaiCharacter
Add `ConvaiCharacter` to each NPC or agent GameObject. One component per character. It owns:
* Character ID — the unique ID from your Convai dashboard
* Session state — `Disconnected`, `Connecting`, `Connected`, `Reconnecting`, `Disconnecting`, `Error`
* Conversation lifecycle — `StartConversationAsync()`, `StopConversationAsync()`, `ToggleSpeech()`
* Transcript and event callbacks — `OnTranscriptReceived`, `OnEmotionChanged`, `OnActionsReceived`, `OnSpeechStarted`, `OnSpeechStopped`, `OnCharacterReady`
* Action configuration — via `ConvaiActionConfigSource` component
`ConvaiCharacter` can be configured inline in the Inspector or via a reusable `ConvaiCharacterProfile` ScriptableObject asset.
#### ConvaiPlayer
Add `ConvaiPlayer` to your player GameObject. One per scene is standard. It owns:
* Player display name and name tag color for transcript attribution
* Text message sending — `SendTextMessage(string message)`
* Runtime identity override — `SetRuntimeDisplayName(string displayName)`
{% hint style="warning" %}
`ConvaiPlayer.PlayerId` is a local display identifier for transcript UI attribution. It is not the server-generated speaker ID used for Long-Term Memory tracking.
{% endhint %}
### Module layer
Modules are optional Unity components you add to the same GameObject as `ConvaiCharacter` (or `ConvaiRoomManager` for Vision). Each module is independent — add only what your project needs.
| Module | What it does |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| LipSync | Real-time blend shape mouth animation driven by audio playback; supports ARKit, MetaHuman, and CC4 Extended maps |
| Emotion | Receives Convai emotion signals, smooths them, and dispatches to blend shape or Animator parameter bindings |
| Vision | Publishes camera, webcam, or Meta Quest passthrough frames to Convai for multimodal awareness |
| Narrative | Manages story section progression through trigger-based events tied to conversation flow |
| DialogueAnimation | Drives a four-layer animator stack (base idle, masked overlays, body talk, head talk) during dialogue |
| FacialAnimation | Plays facial animation clips at runtime, composited against lip sync and emotion outputs |
| Gaze | Blends eye and head actuators toward conversation partners and attention targets |
| Attention | Resolves weighted focus targets, providing gaze direction to the Gaze module |
| ConversationFlow | Bridges the conversation event stream to per-frame dialogue state (Idle, Speaking, Reacting, etc.) |
| Embodiment | Foundational behavior profile and lifecycle management for physical presence and behavioral modules |
`ConversationFlow` is provisioned automatically at runtime when a `ConvaiCharacter` initializes. All other modules — `LipSync`, `Emotion`, `Vision`, `Narrative`, `DialogueAnimation`, `FacialAnimation`, `Gaze`, `Attention`, and `Embodiment` — are opt-in.
### Configuration model
Every major component supports two configuration modes, selectable in the Inspector.
{% tabs %}
{% tab title="Inline" %}
Values are set directly on the component in the Inspector. This is the default mode and is suitable for most scenes — no additional assets required.
{% endtab %}
{% tab title="Asset" %}
Values come from a reusable `ConvaiCharacterProfile` or `ConvaiRoomManagerProfile` ScriptableObject. Use this when you want shared defaults across multiple scenes or prefab variants, or when you need to swap character behavior without modifying individual prefabs.
{% endtab %}
{% endtabs %}
### Next steps
{% content-ref url="/pages/052c621eeaba9b20d93167f3c9981bf9dc20372f" %}
[Feature map](/api-docs/plugins-and-integrations/convai-unity-sdk/overview/feature-map)
{% endcontent-ref %}
{% content-ref url="/pages/1d9fa274483952ca377014dd2a4fb49c2f3e80a1" %}
[Getting started](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started)
{% endcontent-ref %}
# Feature map
Find the right Convai Unity SDK feature, module, guide, or reference page for any development goal, indexed by use case.
Use this table when you know the outcome you want but are not sure which SDK feature, module, or guide covers it.
### Getting started
| I want to... | Feature / Tool | Documentation |
| ------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Install the SDK into my project | Installation | [Installation](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/installation) |
| Configure my Convai API key | API key setup | [Configure API key](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/configure-api-key) |
| Add my first conversational character to a scene | Scene setup | [Build a custom scene](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/build-a-custom-scene) |
| Run a working example without building from scratch | Sample scenes | [Import and run sample scenes](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/import-and-run-sample-scenes) |
| Run a working example with several characters in one session | Multi-Character Sample | [Multi-Character Sample](/api-docs/plugins-and-integrations/convai-unity-sdk/features/multi-character-sessions/multi-character-sample) |
| Understand what each component in the scene does | Component reference | [Scene components reference](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/scene-components) |
| Choose between push-to-talk and hands-free input | Input mode | [Configure conversation input mode](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/configure-conversation-input-mode) |
| Configure character audio output | Audio setup | [Configure character audio](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/configure-character-audio) |
| Configure microphone device and platform permissions | Audio setup | [Configure microphone](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/configure-microphone) |
| Add a chat or subtitle transcript display | Transcript UI | [Add chat UI](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/add-chat-ui) |
| Add real-time lip sync to my character | Lip sync | [Add lip sync](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/add-lip-sync) |
| Verify my scene is set up correctly before shipping | Scene Validator | [Validate your setup](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/validate-your-setup) |
### Authentication
| I want to... | Feature | Documentation |
| ------------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Compare API Key and Auth Token authentication modes | Authentication | [Authentication](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication) |
| Understand how a `ConvaiManager` resolves credentials | Authentication concept | [How authentication works](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/how-authentication-works) |
| Switch a project between API Key and Auth Token mode | Auth mode setup | [Configure auth token mode](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/configure-auth-token-mode) |
| Connect a room session using a short-lived Auth Token | Auth Token connect | [Connect with Auth Token](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/connect-with-auth-token) |
| Supply my own Auth Token minting logic | Custom token provider | [Custom token provider](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/custom-token-provider) |
| Ship a player build without exposing my account API key | Secure build | [Ship a secure build](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/ship-a-secure-build) |
| Call the authentication API from C# | Scripting reference | [Authentication scripting reference](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/scripting-reference) |
### Features
| I want to... | Feature | Documentation |
| ----------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Let my character execute in-scene commands (trigger animations, open doors, move objects) | Actions | [Actions](/api-docs/plugins-and-integrations/convai-unity-sdk/features/character-actions) |
| Inject runtime state or events into the character's knowledge | Dynamic Context | [Dynamic Context](/api-docs/plugins-and-integrations/convai-unity-sdk/features/dynamic-context) |
| Let the character automatically read information about scene objects | Scene Metadata | [Scene Metadata](/api-docs/plugins-and-integrations/convai-unity-sdk/features/scene-metadata) |
| Show facial emotion on my character driven by the AI response | Emotion | [Emotion](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/emotion) |
| Make the character remember players between sessions | Long-Term Memory | [Long-Term Memory](/api-docs/plugins-and-integrations/convai-unity-sdk/features/long-term-memory) |
| Build branching story sections triggered by conversation | Narrative Design | [Narrative Design](/api-docs/plugins-and-integrations/convai-unity-sdk/features/narrative-design) |
| Give my character vision through a camera or webcam | Vision | [Vision](/api-docs/plugins-and-integrations/convai-unity-sdk/features/vision) |
| Decide which character the player is talking to | Conversation Targeting | [Conversation Targeting](/api-docs/plugins-and-integrations/convai-unity-sdk/features/conversation-targeting) |
| Know whether the player can talk right now, and gate my UI on it | Conversation Availability | [Conversation Availability](/api-docs/plugins-and-integrations/convai-unity-sdk/features/conversation-availability) |
### Embodiment
| I want to... | Module | Documentation |
| ---------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------- |
| Make my character look at the player, at objects, or around the scene | Gaze | [Gaze](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze) |
| Time a character's behavior to the phase of the conversation | Conversation Flow | [Conversation flow](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/conversation-flow) |
| Share one set of behavior settings across several characters | Presets | [Embodiment presets](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/embodiment-presets) |
| Decide how much of the face emotion and lip sync each control while speaking | Facial composition | [Facial composition](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/facial-composition) |
| Drive idle, talk, locomotion, and gesture animation from code | Body Animation | [Body Animation](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/body-animation) |
| Direct conversational nonverbal behavior — posture, breathing, listening | Body Language | [Body Language](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/body-language) |
### UI and presentation
| I want to... | Component | Documentation |
| -------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Display a live conversation transcript in my UI | Transcript UI | [Transcript UI](/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/transcript-ui) |
| Switch between chat and subtitle display modes | Presentation modes | [Chat and subtitle modes](/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/transcript-ui/chat-and-subtitle-modes) |
| Query transcript history or react to transcript changes from code | Transcript history | [Transcript history and queries](/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/transcript-ui/transcript-history-and-queries) |
| Show in-world notification popups | Notification system | [Notification system](/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/notification-system) |
| Add a runtime settings panel (mic, transcript, notifications, input) | Settings panel | [Settings panel](/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/settings-panel) |
| Read or apply runtime settings from code | Runtime settings | [Runtime settings API](/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/settings-panel/runtime-settings-api) |
| Customize the look and layout of UI components | UI customization | [Customizing UI components](/api-docs/plugins-and-integrations/convai-unity-sdk/ui-and-presentation/customizing-ui-components) |
### Core concepts
| I want to... | Concept | Documentation |
| -------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Understand the system architecture end-to-end | Architecture | [Convai Unity SDK architecture](/api-docs/plugins-and-integrations/convai-unity-sdk/overview/convai-unity-sdk-architecture) |
| Understand session states, reconnection, and persistence | Session lifecycle | [Session lifecycle](/api-docs/plugins-and-integrations/convai-unity-sdk/core-concepts/session-lifecycle) |
| Compare hands-free, push-to-talk turn-taking | Turn-taking modes | [Turn-taking modes](/api-docs/plugins-and-integrations/convai-unity-sdk/core-concepts/turn-taking-modes) |
| Subscribe to conversation events from C# or Inspector | Event system | [Event System](/api-docs/plugins-and-integrations/convai-unity-sdk/core-concepts/event-system) |
### Scripting reference
| I want to... | API | Documentation |
| ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Subscribe to session connected / disconnected / error events | Session events | [Session Events](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/session-events) |
| Subscribe to transcript, emotion, and turn events | Character events | [Character Events](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/character-events) |
| Read and clear transcript history at runtime | Transcript API | [Transcript API](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/transcript-api) |
| Use the `ConvaiSDK` and `ConvaiAudio` static facades | Conversation facades | [ConvaiManager API](/api-docs/plugins-and-integrations/convai-unity-sdk/scripting-reference/convaimanager-api) |
| Understand `IConvaiOperationspace.vars.unity\_sdk\_version.
{% updates format="full" %}
{% update date="2026-09-04" tags="v4.6.0,Current" %}
## v4.6.0
**Breaking this release:** `SetExplicitConversationTarget` renames to `SetInitialCharacter`, three Gaze profile Conversation Attention fields are removed and replaced, `headStabilityDegrees` is removed, two Gaze profile defaults changed, and the microphone open timing in multi-character scenes changed. See **Breaking changes and migration** below.
**Multi-character conversations**
* Conversation targeting moved into the SDK: no component to add, no collider, no layer, and no field to fill. `ConvaiManager.ConversationTargeting` reads the player's view by default and scores every candidate by angle with distance as a tiebreak, so it works the same on a mouse, a gamepad, and a head-mounted display. `Mode` chooses `LookAt`, `Proximity`, or `Manual`; `ConvaiManager.TalkTo(character)` points the conversation explicitly for scripted moments
* A room now opens on the character the player is looking at, instead of always the first character in scene order. An assigned **Convai Manager > Initial Character** still wins outright, and the Console names the character it opened on and why
* A character that joins or leaves a connected room is added or removed live, with no reconnect — instantiating a character prefab, or enabling a character `GameObject`, is the whole integration. A room that connected with a single character carries no roster and cannot grow live; the Console names that case and what to do instead
* `ConvaiManager.Events` gains `OnConversationAvailabilityChanged`, `OnConversationTargetChanged` (with phases `Requested`, `Confirmed`, `Failed`), and `OnRoomRosterChanged`
* `Convai.ConfigureConversationTargeting` joins the MCP and Unity Assistant tool set, and `Convai.DiagnoseConversation` reports the roster, the addressed character, and the targeting verdict. Tool contract version `7`
* A **Multi-Character Sample** ships alongside the existing Basic and LipSync samples
**Conversation availability**
* `ConvaiManager.ConversationAvailability` answers whether the player can talk right now — `Offline`, `Connecting`, `Preparing`, `Ready`, `Answering`, `Unavailable` — for `ConvaiManager.AddressedCharacter`, with `ConversationAvailabilityChanged` reporting each move and `CanAcceptPlayerInput()` as the question a UI asks. The same answer is available per character on `ConvaiCharacter.ConversationAvailability`
* The shipped chat field, push-to-talk, and hands-free input all consult this now. The chat field disables until the character can hear, and `ConvaiPlayer.TrySendTextMessage` refuses with a reason a project can show instead of dropping the message silently
* **Behaviour change:** in multi-character scenes the microphone now opens when the room confirms its first character, rather than when the transport connects — typically a fraction of a second later. Single-character rooms are unaffected
**Gaze**
* **Attend To Speaker** on the Gaze component now follows the conversational floor — the player, another character, or both — while a character is not in its own turn, so listeners in a room with more than one participant react to whoever is speaking instead of sitting in `Idle`. Four new settings in the profile's **Conversation** group tune the model: **Typical Pause Before Turning**, **How Much Reactions Vary**, **How Long Attention Fades Over**, and **Shortest Gap Between Listeners Turning**
* Listener attention is now a per-participant value that rises on a speech onset and decays continuously, fixing listeners that turned to a new speaker late, together, or to the wrong person
* The head and chest now follow a moving target continuously instead of in bursts, removing the dead band that caused parked holds and whip-like corrections. A camera cut is now treated as an ordinary look rather than a startle. **Head Speed Limit** drops from 240°/s to 150°/s, and **Turn Speed (Rigs Without Turn Animation)** drops from 140°/s to 90°/s — both are safety ceilings; profiles already authored keep their saved values
**Speech and performance**
* On a character with Lip Sync, the speaking turn now ends on lip sync's own frame data rather than waiting on the silence detector or the service's confirmation, so a character stops performing when its voice stops rather than up to two seconds later. `ConvaiCharacter.IsSpeaking`, `OnSpeechStopped`, and `OnTurnCompleted` are unaffected. The Conversation Flow profile carries a `stopWhenTheVoiceStops` switch for the previous timing, but it ships on and is not exposed in the profile's Inspector or through a public setter, so the new timing is what every character gets
* A character's mouth now settles closed at the end of a sentence instead of hanging open or snapping shut: a new **Settle Duration** (0.35 s) on the Lip Sync component drives a spring-based close, and `LipSyncPlaybackEngine.SettleToRest()` triggers it from code
* A talking hand no longer freezes mid-gesture when a response ends — the gesture now decelerates to rest as its weight fades, starting **Talk Release Lead Seconds** (0.6 s) before the response actually ends
* Lip sync no longer stalls after the first response in a session; every later response now plays with a moving mouth instead of a still one
* `ConvaiCharacter.OnTranscriptReceived` fires. It previously read a message the service does not send, so it never fired in any room and everything downstream of it sat idle — gaze referential glances, and any `IConvaiCharacterBehavior` reacting to what a character said. It now reads the room transcript feed, and its `isFinal` argument comes from the message's own lifecycle instead of being hard-coded to `false`, so consumers gating on the final utterance work. Two consequences: text arrives per sentence rather than per synthesis chunk, and a line that streams before it settles is delivered twice — once interim, once final
**Editor and inspector work**
* Multi-character controls in the **Convai Manager** inspector were renamed for clarity: *Include in Next Room* is now **Characters Joining the Room**, *Within* is **Range (Metres)**, *Seen From* is **Player Camera**, *Scene Characters* is **Characters in Scene**, and *Roster room* / *Single character* are **Several characters** / **One character only**
* The **Convai Manager** inspector's Live section now names who is being addressed, whether the player can talk to them, and one row per character in the room with its status
* The Character inspector now flags a duplicated Character ID before Play mode, instead of only when the room refuses to connect
* The **Convai Player** and **Convai Room Manager** Validation sections were redesigned with a header that reflects the worst check found, instead of a permanently amber header
* Every Convai inspector section now shares one left-edge alignment and one section-padding system
**Unity 6000.5 compatibility**
* The package compiles on Unity 6000.5 again. Unity's scene identity move to a 64-bit `EntityId`, and the deprecation of `Object.GetInstanceID()`, are now routed through compatibility seams (`ConvaiSceneId`, `ConvaiObjectId`, `ConvaiObjectFind`), so ids are unchanged on `6000.0` through `6000.3` and agree with the old ones on `6000.4` and later
**Package dependencies**
* `com.unity.ai.inference` `2.2.1` is a new dependency, for client-side voice activity detection
* `com.unity.nuget.newtonsoft-json` `3.2.2`, `com.unity.ugui` `2.0.0`, and `com.unity.inputsystem` `1.19.0` are retained
* `com.unity.ai.navigation`, `com.unity.collections`, and `com.unity.modules.xr` are no longer declared dependencies
**Breaking changes and migration**
* **`ConvaiManager.SetExplicitConversationTarget` is renamed to `ConvaiManager.SetInitialCharacter`.** The old name is still callable and marked `[Obsolete]`. The rename exists because the old name read like the verb for changing who the player is talking to, but it chooses which character speaks first, and calling it on a connected room queues an ownership reconnect rather than moving the conversation. Replace `SetExplicitConversationTarget(character)` with `SetInitialCharacter(character)` for the same behavior; use `TalkTo(character)` to switch the conversation in a running room
* **The Gaze profile's Conversation Attention fields are removed:** **Shortest/Longest Delay Before Turning**, **Stays With The Conversation For**, and **Looks To Whoever Answers Next**, along with `ConvaiGazeProfile.SpeakerAttentionReactionDelayMin/Max`, `SpeakerAttentionLingerSeconds`, and `SpeakerAttentionHandOffGlanceChance`. Their replacements are **Typical Pause Before Turning**, **How Much Reactions Vary**, **How Long Attention Fades Over**, and **Shortest Gap Between Listeners Turning**. A profile carrying the removed fields loses them silently on its next save — re-apply a personality, or leave the defaults, to pick up the new attention model's tuning
* **The Gaze profile's Ignore Small Target Movement (`headStabilityDegrees`) is removed.** Its replacements on **Head & Body** are **How Quickly The Head Follows Movement** (`HeadFollowSeconds`, default 0.2 s) and **How Quickly The Chest Follows Movement** (`TorsoFollowSeconds`, default 0.35 s). A profile carrying the removed field ignores it from the moment it loads and drops it on its next save; lower **How Quickly The Head Follows Movement** if a fast target trails the head more than wanted
* **Two Gaze profile defaults changed:** **Neck Relaxes During A Turn** (`bodyTurnHeadRelief`) from `0.4` to `1`, and **Chest Speed Limit** (`maxTorsoAngularSpeed`) from `180°/s` to `90°/s`. Existing profiles keep their saved values — only new profiles pick up the new defaults. To pick up the new defaults on an existing profile, set both values by hand
* **Behaviour change:** in multi-character scenes the microphone now opens when the room confirms its first character, rather than when the transport connects
{% endupdate %}
{% update date="2026-08-14" tags="v4.5.0" %}
## v4.5.0
**Character embodiment**
Five behavior modules now share one component family under **Add Component > Convai > Embodiment**, and each module reads the same dialogue state.
* **Convai Gaze** (`ConvaiGazeController`) replaces the previous Gaze implementation and the Attention module. It decides what the character looks at and performs the look in one component: eye-contact styles (`Natural`, `Speaking Focus`, `Conversation Lock`, `Always Lock`), `ConvaiGazeTarget` for scene objects with priority tier and aim offset, `PlayerAttentionSensor` for "is the player looking at me", a whole-body look-sharing ladder from eyes to head to chest to feet, and an XR eye-tracking extension point through `IPlayerGazeRaySource`
* **Convai Body Animation** (`ConvaiBodyAnimationController`) replaces Dialogue Animation. It builds its own layered `PlayableGraph` in code, so there is no Animator Controller asset to author. It covers idle and talk variants, co-speech gestures, target-aimed gestures, and NavMesh-synced walking with directional starts, planted stops, and turns in place. Animation clips and `ConvaiBodyAnimationSet_Female` ship with the module
* **Convai Body Language** (`ConvaiBodyLanguageController`) is new: breathing, weight shifts, sway, posture pulses, speech-timed head beats, listening lean-in, idle fidget, and startle or amused reactions. It layers on top of the Animator without owning a clip and needs no imported content
* **Emotion** gained semantic expression recipes that resolve onto ARKit, Reallusion CC3 and CC4, and MetaHuman rigs with no per-character authoring, plus resting mood, mood drift, a micro-expression idle layer, and shader-property output. `ConvaiEmotionController.SetMood(label, intensity, transitionSeconds)` and `ClearMood(transitionSeconds)` control mood at runtime, and `DominantEmotionChanged` and `MoodChanged` report resolved expression. Four personalities ship: Composed, Warm, Energetic, and Reserved
* **Conversation flow** supplies the dialogue state the other four modules read
**Character Actions**
* The **Actions Editor** window (**Convai > Actions Editor**) adds reusable Action Sets, Scene Knowledge, Character Settings, and a Live mode with batch progress, timeline, target registry, and per-action insights. The **Try It** box previews an action in Edit mode and dispatches it in Play mode
* Four built-in executors are new: Lead Player To Target, Scan Environment, Count Target Group, and Measure Distance
* `ConvaiActionExecutionResult.Answered("…")` lets an action supply a sentence the character can speak, separate from the diagnostic `Message`. **When It Finishes** authors this per action
* `ConvaiActionFailureReason` reports a typed failure cause on `ConvaiActionExecutionResult` and `ConvaiActionStepReport`. `ConvaiActionParameterValue.Presence` distinguishes an unfilled slot from a blank one. `ConvaiActionDispatcher` exposes `IsBusy`, `PendingBatchCount`, and `CurrentActionName`
* `ConvaiActionExecutorBase`, `ConvaiTargetedActionExecutor`, and `ConvaiCharacterActionExecutorspace.vars.unity\_min\_version, and there is no supported configuration on an earlier Unity release. The pages below cover Unity version support, render pipeline compatibility, platform-specific constraints, and network requirements.
| Unity versions and render pipelines Minimum Unity version, required packages, and render pipeline support. | Unity versions and render pipelines |
| Platform support matrix Feature availability across Windows, macOS, Android, iOS, Meta Quest, and WebGL. | Platform support matrix |
| Network and API requirements Domains, ports, and firewall rules needed for real-time SDK operation. | Network and API requirements |
space.vars.unity\_min\_version. There is no supported configuration on an earlier Unity release, and the SDK compiles on Unity `6000.5` now that Unity moved scene identity to 64-bit. All three Unity render pipelines are supported with no additional configuration, and both installation methods — Package Manager and Asset Store — resolve the required package dependencies automatically.
### Unity version requirements
| Requirement | Version |
| ---------------------------- | ---------------------------------------------------------------------- |
| Minimum | space.vars.unity\_min\_version |
| Recommended for new projects | space.vars.unity\_recommended\_version |
{% hint style="warning" %}
The minimum is a hard floor. Convai supports no configuration below Unity space.vars.unity\_min\_version, including earlier LTS releases. Upgrade the project before installing the SDK.
{% endhint %}
### Required package dependencies
The SDK depends on four Unity packages. Both installation methods install these automatically — you do not need to add them manually unless you encounter a version conflict.
| Package | Version |
| --------------------------------- | ------------------------------------------------------------------------- |
| `com.unity.ai.inference` | space.vars.dep\_ai\_inference\_version |
| `com.unity.nuget.newtonsoft-json` | space.vars.dep\_newtonsoft\_json\_version |
| `com.unity.ugui` | space.vars.dep\_ugui\_version |
| `com.unity.inputsystem` | space.vars.dep\_inputsystem\_version |
{% hint style="warning" %}
Do not downgrade these packages after installation. The SDK targets the versions listed above and behavior on lower versions is undefined. If your project already pins an older version of any of these in `Packages/manifest.json`, remove or update the pin before installing.
{% endhint %}
NavMesh-driven locomotion needs one more package the SDK does not install. `ConvaiNavMeshLocomotion` drives a built-in Unity `NavMeshAgent`, but NavMesh authoring — `Window > AI > Navigation` and the `NavMeshSurface` component — comes from `com.unity.ai.navigation`. If your project bakes a NavMesh for character movement, install `com.unity.ai.navigation` yourself through Package Manager.
### Render pipeline support
The SDK detects the active render pipeline at runtime and adapts automatically. The Vision module's camera capture path, for example, uses built-in render hooks when no render pipeline asset is assigned and an explicit render path on URP and HDRP. All three Unity render pipelines are fully supported with no manual configuration required.
| Render Pipeline | Supported |
| -------------------------------------- | --------- |
| Built-in Render Pipeline | ✅ Full |
| Universal Render Pipeline (URP) | ✅ Full |
| High Definition Render Pipeline (HDRP) | ✅ Full |
Support requires no manual configuration on any pipeline, but the Vision module's `CameraVisionFrameSource` captures differently depending on the pipeline. On the Built-in pipeline it uses command-buffer render hooks with no extra render pass. On URP and HDRP it falls back to an explicit render-compatibility path that issues one additional `Camera.Render()` call per captured frame.
The included sample scenes use URP materials. If your project uses the Built-in or HDRP pipeline, sample scene materials require reassignment. The optional depth-of-field camera scripts in `SamplesShared/Camera/` support URP and HDRP; on the Built-in pipeline they skip depth-of-field and log a warning instead. None of these scripts are required for SDK functionality.
### Next steps
With your Unity version and packages confirmed, check which platforms you are targeting.
{% content-ref url="/pages/e8f8a0a8257efa9a6ff3e80c02b6bdc1224d50fc" %}
[Platform support matrix](/api-docs/plugins-and-integrations/convai-unity-sdk/compatibility-and-requirements/platform-support-matrix)
{% endcontent-ref %}
# Platform support matrix
Reference for Convai Unity SDK platform support, including feature availability across Windows, macOS, Android, iOS, Meta Quest, and WebGL.
The Convai Unity SDK runs on all major Unity deployment targets. Feature availability varies by platform — use the matrix below to confirm support before building for a specific target.
### Feature × platform matrix
| Feature | Windows / macOS / Linux | Android | iOS | Meta Quest | WebGL |
| -------------------------- | ----------------------- | ------------------------------ | -------------------------------------- | --------------------- | -------------------------------------- |
| Voice conversation | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
| Microphone capture | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full — HTTPS + user gesture required |
| Remote audio playback | ✅ Unity `AudioSource` | ✅ Unity `AudioSource` | ✅ Unity `AudioSource` | ✅ Unity `AudioSource` | ⚠️ Browser-routed |
| Lip sync | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ⚠️ Known timing drift |
| Spatial audio | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ❌ Not supported |
| Actions | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
| Emotion | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
| Long-Term Memory | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
| Narrative Design | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
| Dynamic Context | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
| Vision — Camera | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ⚠️ Canvas capture |
| Vision — Webcam | ✅ Full | ⚠️ Runtime permission required | ⚠️ `NSCameraUsageDescription` required | ❌ Not applicable | ❌ Not supported |
| Vision — Quest passthrough | ❌ Not supported | ❌ Not supported | ❌ Not supported | ✅ Full | ❌ Not supported |
### Platform-specific requirements
{% tabs %}
{% tab title="WebGL" %}
WebGL is fully supported with the following constraints imposed by browser security policies:
* **Microphone capture** requires HTTPS or `localhost`. HTTP deployments cannot access the microphone. Call `ConvaiManager.EnableAudioAndStartListening()` from a user gesture (button click) — do not start audio automatically on scene load.
* **Remote audio playback** is routed through the browser's audio system, not Unity's `AudioSource`. Volume and spatialization controls on `AudioSource` components have no effect on WebGL.
* **Vision — Camera** uses browser canvas capture (`CameraVisionFrameSource` is supported).
* **Vision — Webcam** (`WebcamVisionFrameSource`) is not supported on WebGL — `AsyncGPUReadback` is unavailable in the browser runtime. Use `CameraVisionFrameSource` to stream the game canvas instead.
* **Spatial audio** is not supported on WebGL.
{% hint style="warning" %}
WebGL has a known audio/lip-sync timing drift defect — audio and lip-sync data arrive correctly, but playback timing can drift in browser builds. This is a tracked defect, not a missing feature. Validate in your target browser before shipping.
{% endhint %}
{% hint style="info" %}
Always validate WebGL builds in the actual hosting environment, especially if the build is embedded in an iframe. Add `allow="microphone"` to the iframe tag if you embed the build in a page you control.
{% endhint %}
For detailed WebGL setup, browser compatibility, and deployment steps, see the WebGL platform guide.
{% content-ref url="/pages/7b2c74ff6faeac7d9557447799d0496b11e50783" %}
[WebGL](/api-docs/plugins-and-integrations/convai-unity-sdk/platform-guides/webgl)
{% endcontent-ref %}
{% endtab %}
{% tab title="Android" %}
* **Microphone:** The SDK requests `RECORD_AUDIO` permission at runtime via `ConvaiPermissionService`. Declare the permission in your `AndroidManifest.xml` and handle both grant and denial cases in your app flow.
* **Vision — Webcam:** `android.permission.CAMERA` is requested at runtime by `WebcamVisionFrameSource`. Handle permission grant and denial in your app flow.
For Android build configuration, permission handling, and microphone setup, see the iOS and Android platform guide.
{% content-ref url="/pages/32708cb5ab33fa2d1d0f91e747cc06da20220bc1" %}
[iOS and Android](/api-docs/plugins-and-integrations/convai-unity-sdk/platform-guides/ios-and-android)
{% endcontent-ref %}
{% endtab %}
{% tab title="iOS" %}
* **Microphone:** `NSMicrophoneUsageDescription` must be set in **Player Settings → Other Settings → iOS → Microphone Usage Description**. Omitting this causes a crash on first microphone access.
* **Vision — Webcam:** `NSCameraUsageDescription` must be set in **Player Settings → Other Settings → iOS → Camera Usage Description** if you use `WebcamVisionFrameSource`. On iOS, `WebcamVisionFrameSource` accesses the device camera via Unity's `WebCamTexture` API.
* Define your app's behavior when the user denies microphone or camera permission, and when the app is interrupted or backgrounded during a conversation.
For iOS build configuration, permission setup, and Info.plist requirements, see the iOS and Android platform guide.
{% content-ref url="/pages/32708cb5ab33fa2d1d0f91e747cc06da20220bc1" %}
[iOS and Android](/api-docs/plugins-and-integrations/convai-unity-sdk/platform-guides/ios-and-android)
{% endcontent-ref %}
{% endtab %}
{% tab title="Meta Quest" %}
Quest passthrough vision (`QuestVisionFrameSource`) is supported on **Quest 3 and Quest 3S only**.
**Requirements:**
* Meta XR SDK imported into your project
* `PassthroughCameraAccess` component present in the scene
* The `horizonos.permission.HEADSET_CAMERA` and `android.permission.CAMERA` permissions granted to the app
The Convai Unity SDK does not ship an `AndroidManifest.xml` and does not declare or request these permissions itself — `QuestVisionFrameSource` requires both to already be granted. Declare them in your project's manifest and confirm they are granted before relying on passthrough capture.
On other Quest hardware or non-Quest platforms, `QuestVisionFrameSource` produces no frames. Use `CameraVisionFrameSource` or `WebcamVisionFrameSource` instead.
`WebcamVisionFrameSource` is not applicable on Meta Quest because Quest does not expose a standard `WebCamTexture` device.
For Meta Quest project setup, XR SDK configuration, and passthrough Vision integration, see the XR headsets platform guide.
{% content-ref url="/pages/86442e40afdd1c7fd12eb8dc8331a0cc75827347" %}
[XR headsets](/api-docs/plugins-and-integrations/convai-unity-sdk/platform-guides/xr-headsets)
{% endcontent-ref %}
{% endtab %}
{% endtabs %}
### Next steps
With platform constraints confirmed, review the network requirements for real-time SDK operation.
{% content-ref url="/pages/451345facd5cd16f0b40e81f6f7a06784935c82b" %}
[Network and API requirements](/api-docs/plugins-and-integrations/convai-unity-sdk/compatibility-and-requirements/network-and-api-requirements)
{% endcontent-ref %}
# Network and API requirements
Explains which network hosts, ports, and firewall rules a Unity project must allow before it can connect to Convai over the internet.
The Convai Unity SDK requires outbound internet access during runtime. Speech, language understanding, and text-to-speech run through Convai over HTTPS and LiveKit WebRTC — there is no offline or LAN mode. Use this page when preparing a corporate network, validating a firewall allowlist, or confirming that a Play mode session reached the correct LiveKit room.
### Required outbound access
Runtime sessions use two Convai endpoints plus LiveKit hosts returned in the connect response. Allow outbound traffic from the machine running Unity to the hosts below.
#### Convai endpoints
| Host | Port | Protocol | Purpose |
| ------------------------------------------------------------ | ----- | -------- | --------------------------------------------------------- |
| space.vars.live\_server\_url | `443` | HTTPS | Connect API — session setup and room credentials |
| `api.convai.com` | `443` | HTTPS | Character metadata, REST API, and WebGL emotion preflight |
#### LiveKit minimum requirements
After Convai accepts the connect request, the SDK joins a LiveKit room using the `room_url` and `token` from the response. Minimum outbound rules for LiveKit Cloud connectivity:
| Host | Port | Protocol | Purpose |
| -------------------------------------------- | ----- | -------- | ------------------------------------- |
| `convai-technologies-lfslae7c.livekit.cloud` | `443` | TCP | Convai LiveKit signaling endpoint |
| `*.livekit.cloud` | `443` | TCP | LiveKit WebSocket signaling |
| `*.turn.livekit.cloud` | `443` | TCP | TURN/TLS fallback when UDP is blocked |
#### Optional direct media paths
LiveKit documents these paths for direct WebRTC media and TCP fallback. Add them when your network policy permits UDP or when the LiveKit connection test shows that the minimum TCP rules are not enough.
| Host | Port | Protocol | Purpose |
| ---------------------- | --------------- | -------- | ---------------------- |
| `*.host.livekit.cloud` | `3478` | UDP | TURN/UDP connectivity |
| All LiveKit hosts | `50000`–`60000` | UDP | WebRTC media transport |
| All LiveKit hosts | `7881` | TCP | WebRTC TCP fallback |
No inbound ports are required on the client machine. For the full LiveKit firewall reference, see [Configuring firewalls](https://docs.livekit.io/deploy/admin/firewall/) in the LiveKit documentation.
### How realtime sessions connect
Each character session follows this sequence:
```mermaid
sequenceDiagram
participant Unity as Unity SDK
participant Convai as Convai
participant LiveKit as LiveKit room
Unity->>Convai: POST /connect with API key
Convai-->>Unity: session_id, room_url, room_name, token
Unity->>LiveKit: Join room at room_url with token
LiveKit-->>Unity: Audio, video, and data streams
```
| Connect response field | Runtime use |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| `session_id` | Convai session ID for the live session |
| `character_session_id` | Conversation continuity across reconnects |
| `room_url` | LiveKit WebSocket endpoint — for example `wss://convai-technologies-lfslae7c.livekit.cloud` |
| `room_name` | LiveKit room name the client joins |
| `token` | Temporary LiveKit room token used to join the room |
The SDK reads `room_url` from the connect response and passes it to the transport layer. It does not hardcode a LiveKit hostname. The example host `convai-technologies-lfslae7c.livekit.cloud` is one Convai deployment; your logs may show a different `room_url` for the same account over time.
### Authentication
Two credential types are involved in a runtime session.
#### API key
Your project API key authenticates requests to Convai. Store it in **Edit > Project Settings > Convai SDK**.
| Request type | Header | Used for |
| ----------------------- | ---------------- | ---------------------------------------------------------- |
| Connect (`/connect`) | `X-API-Key` | Starting a realtime session |
| REST (`api.convai.com`) | `CONVAI-API-KEY` | Character metadata, long-term memory, and other REST calls |
The SDK sends the API key automatically. You do not paste the key into connect payloads manually.
#### LiveKit room token
Each successful connect response includes a temporary `token`. The SDK passes this token to LiveKit when joining the room. The token is short-lived and grants access only to that room. Treat it like a password — do not share it in public forums, support tickets, or version control.
### Find connection details in logs
When a session starts, the SDK logs room credentials at **Debug** level under the **Transport** category. Enable verbose transport logging before searching for these lines.
1. Open **Edit > Project Settings > Convai SDK > Diagnostics**.
2. Set **Global Log Level** to `Debug`, or expand **Category Overrides** and add an override with **Category** `Transport` and **Level** `Debug`.
3. Enter Play mode and start a character session.
4. Open the Unity Console and filter by `Transport`.
You should see one of these log forms:
```
[Debug][Transport]: Room details received: {"token":"...","room_name":"...","session_id":"...","room_url":"..."}
```
If the JSON line is hard to read, search for `Token:` — the SDK also prints a readable summary:
```
[Debug][Transport]: Token: ...; Room Name: ...; Room URL: ...; Session ID: ...; Character Session ID: ...
```
| Log field | Meaning |
| ---------------------- | ------------------------------------------------------- |
| `token` | LiveKit room token |
| `room_name` | LiveKit room name / room ID |
| `room_url` | LiveKit URL / WebSocket endpoint |
| `session_id` | Convai session ID |
| `Character Session ID` | Convai character session ID for conversation continuity |
{% hint style="danger" %}
Do not share the room token publicly. It is temporary and grants access to the LiveKit room. Redact `token` values before posting logs to support channels or public issue trackers.
{% endhint %}
Debug log calls compile out of non-development builds unless `CONVAI_DEBUG_LOGGING` is defined. Debug transport lines appear in the Unity Editor and Development Builds by default. See [Debug tools reference](/api-docs/plugins-and-integrations/convai-unity-sdk/troubleshooting/debug-tools-reference) for logging configuration.
### Test the LiveKit connection
Use the [LiveKit connection test](https://livekit.com/webrtc/connection-test) when you need to confirm whether a restricted network can reach the room returned by Convai.
1. Start a Unity session and find the `Token:` log line.
2. Copy the `Room URL` value into **LiveKit URL**.
3. Copy the `Token` value into **Room Token**.
4. Select **Run test**.
| Connection test field | Value from Convai logs |
| --------------------- | ----------------------- |
| **LiveKit URL** | `room_url` / `Room URL` |
| **Room Token** | `token` / `Token` |
The test validates LiveKit signaling and WebRTC connectivity for that temporary room. It does not validate your Convai API key, `api.convai.com`, or character configuration.
### Firewall validation checklist
Work through this checklist with your network or IT team before deploying to a restricted environment.
1. Confirm outbound TCP `443` to space.vars.live\_server\_url and `api.convai.com`.
2. Confirm outbound TCP `443` to `convai-technologies-lfslae7c.livekit.cloud`, `*.livekit.cloud`, and `*.turn.livekit.cloud`.
3. When UDP is permitted, allow UDP `3478` to `*.host.livekit.cloud` and outbound UDP `50000`–`60000`.
4. Exclude Convai and LiveKit hostnames from TLS inspection if your proxy performs man-in-the-middle decryption on HTTPS or WSS traffic.
5. Enter Play mode, enable **Transport** logs at **Debug**, and confirm a `Room details received` or `Token:` line appears with a `wss://` `room_url`.
6. Confirm the character reaches **Connected** state and responds to voice or text input.
If steps 5 or 6 fail with `transport.ice_failed` or `transport.signal_disconnected`, see [Connection and API issues](/api-docs/plugins-and-integrations/convai-unity-sdk/troubleshooting/connection-and-api-issues).
### Troubleshooting
| Symptom | Likely cause | Fix | Verify |
| ------------------------------------------------------------ | --------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `connection.network_error` or `connection.timeout` | Convai endpoints blocked on TCP `443` | Allow space.vars.live\_server\_url and `api.convai.com` | Session reaches `Connected` state |
| `transport.ice_failed` or `transport.peer_connection_failed` | LiveKit UDP or TURN hosts blocked | Add the LiveKit minimum rules and optional direct media paths from this page | `Room details received` log appears; character responds in Play mode |
| No `Room details received` log line | Transport logging below **Debug** | Open **Diagnostics** in Project Settings; set **Transport** category override to **Debug** | Readable `Token:` line appears in the Console |
| LiveKit connection test fails after connect succeeds | UDP media or TURN fallback path blocked | Allow UDP `50000`–`60000`, UDP `3478` to `*.host.livekit.cloud`, and TCP `443` to `*.turn.livekit.cloud` | LiveKit connection test succeeds with the logged `Room URL` and `Token` |
| `connection.connect_invalid_api_key` | Invalid or revoked API key | Copy a fresh key from the [Convai dashboard](https://convai.com) into Project Settings | Connect error no longer fires |
| WebGL mic unavailable | Build served over HTTP | Serve the build over HTTPS or from `localhost` | Microphone permission prompt appears in the browser |
{% hint style="warning" %}
Proxy servers that perform TLS inspection on HTTPS or WSS traffic can break LiveKit signaling. Exclude Convai and LiveKit hostnames from TLS inspection when your environment uses a corporate proxy.
{% endhint %}
### WebGL deployments
WebGL builds must be served over HTTPS or from `localhost`. HTTP deployments block microphone access due to browser security policy. WebGL uses the same Convai and LiveKit endpoints as desktop builds. See [Platform support matrix](/api-docs/plugins-and-integrations/convai-unity-sdk/compatibility-and-requirements/platform-support-matrix) and the [WebGL deployment guide](/api-docs/plugins-and-integrations/convai-unity-sdk/platform-guides/webgl) for browser-specific constraints.
### Next steps
With network requirements confirmed, install the SDK or review connection error codes.
{% content-ref url="/pages/f1aef51364acf8a4bf5802a99774c033d9ee6e68" %}
[Install the Convai Unity SDK](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/installation)
{% endcontent-ref %}
{% content-ref url="/pages/bf2d3c0310bc8496a310e6c0331136dd3cf2399d" %}
[Connection and API issues](/api-docs/plugins-and-integrations/convai-unity-sdk/troubleshooting/connection-and-api-issues)
{% endcontent-ref %}
# Getting started
Step-by-step path from installing the Convai Unity SDK to a validated, working conversational AI character in your scene.
By the end of this section, your project contains a responsive AI character that listens, processes speech through Convai, and responds in real time. Follow the pages in order — each step builds directly on the previous one.
{% hint style="info" %}
**Before you begin:** Confirm your environment meets the requirements on the [Prerequisites](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/prerequisites) page — Unity space.vars.unity\_min\_version, required packages, and a Convai account with an API key.
{% endhint %}
### Preparation
| Prerequisites Unity version, required packages, and account requirements before installing. | Prerequisites |
| Installation Add the Convai Unity SDK to your project via the Package Manager or Asset Store. | Install the Convai Unity SDK |
| Configure API key Connect your project to Convai with your account API key. | Configure the API key |
| Import and run sample scenes Verify the SDK works before building your own scene. | Import and run sample scenes |
| Multi-Character Sample Import a shared-room sample scene with several characters, interaction targeting, and a live transcript. | Multi-Character Sample |
| Scene components reference Learn what ConvaiManager, ConvaiCharacter, and ConvaiPlayer do and how they depend on each other. | Scene components reference |
| Build a custom scene Build a Convai scene from scratch using the Setup Required Components command. | Build a custom scene |
| Validate your setup Run the scene validator to confirm required components are present before adding features. | Validate your setup |
| Configure conversation input mode Choose between hands-free and push-to-talk input. | Configure conversation input mode |
| Configure character audio Tune NPC voice volume, spatial audio, and mute controls. | Configure character audio |
| Configure microphone Select the active microphone device and set up platform permissions for Android, iOS, and WebGL. | Configure microphone |
| Add chat UI Display conversation transcripts in your scene. | Add chat UI |
| Add lip sync Drive character blendshapes in sync with voice audio. | Add lip sync |
space.vars.unity\_min\_version |
| Scripting backend | Mono or IL2CPP |
| Internet connection | Required at editor time and runtime |
{% hint style="warning" %}
Unity space.vars.unity\_min\_version is a hard floor — there is no supported configuration on an earlier release, including older LTS versions such as Unity 2022 or Unity 2023. If your project targets an older release, upgrade the project to Unity 6 before installing the SDK. There is no workaround.
{% endhint %}
### Required Unity packages
The SDK depends on four Unity packages. Both installation methods (Package Manager and Asset Store) install these automatically — you do not need to add them manually unless you encounter a version conflict.
| Package | Minimum version |
| --------------------------------- | ------------------------------------------------------------------------- |
| `com.unity.ai.inference` | space.vars.dep\_ai\_inference\_version |
| `com.unity.nuget.newtonsoft-json` | space.vars.dep\_newtonsoft\_json\_version |
| `com.unity.ugui` | space.vars.dep\_ugui\_version |
| `com.unity.inputsystem` | space.vars.dep\_inputsystem\_version |
If your project already pins any of these packages to an older version in `Packages/manifest.json`, the automatic install fails silently or produces a version conflict. Remove or update the existing version pins before installing the SDK.
### Supported render pipelines
| Render Pipeline | Supported |
| -------------------------------------- | --------- |
| Built-in Render Pipeline | ✓ |
| Universal Render Pipeline (URP) | ✓ |
| High Definition Render Pipeline (HDRP) | ✓ |
For detailed platform and render pipeline compatibility, see [Compatibility & Requirements](/api-docs/plugins-and-integrations/convai-unity-sdk/compatibility-and-requirements).
### Account requirements
You need an active Convai account and an API key to connect your project to Convai during local development.
1. Create an account at [convai.com](https://convai.com) if you do not have one.
2. Retrieve your API key from the **API Keys** section of the Convai dashboard.
3. Create at least one character in the Convai dashboard and note its **Character ID** — you need it during scene setup.
Your API key is stored in `Assets/Resources/ConvaiSettings.asset`. This is the **API Key** authentication mode, intended for local development in the Unity Editor rather than for a build you distribute. See [Configure the API key](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/configure-api-key) for full setup steps.
If your project ships to testers or players, the SDK also supports **Auth Token** mode, which resolves a short-lived credential per connection instead of shipping your account API key in the build. Review the two modes and decide which one your project needs before you reach scene setup.
{% content-ref url="/pages/Qz3amgJ54KyHWFyUqBBJ" %}
[Authentication](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication)
{% endcontent-ref %}
### Next steps
Once your environment meets all requirements above, install the SDK.
{% content-ref url="/pages/f1aef51364acf8a4bf5802a99774c033d9ee6e68" %}
[Install the Convai Unity SDK](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/installation)
{% endcontent-ref %}
# Install the Convai Unity SDK
Install the Convai Unity SDK into a Unity project using Package Manager or Asset Store so the SDK and its dependencies resolve correctly.
The Convai Unity SDK is available through two channels. Use **Package Manager** for new projects or when you prefer not to manage Asset Store downloads — the package resolves directly from the Convai registry with no manual download. Use **Asset Store** if your project already sources packages from your Asset Store library or if your studio manages package versions through My Assets.
Both methods require Unity space.vars.unity\_min\_version and install SDK version space.vars.unity\_sdk\_version and the same four required dependencies.
{% tabs %}
{% tab title="Package Manager" %}
{% stepper %}
{% step %}
#### Open Package Manager
In the Unity Editor menu bar, select **Window > Package Manager**.
The Package Manager window opens. Confirm you are connected to the internet before proceeding.
{% endstep %}
{% step %}
#### Add package by name
Click the **+** button in the top-left corner of the Package Manager window. Select **Add package by name** from the dropdown.
A text field appears prompting for the package name.
{% endstep %}
{% step %}
#### Enter the package name
Type or paste the following identifier into the Name field, then click **Add**:
```
com.convai.convai-sdk-for-unity
```
Unity contacts the registry, resolves the package, and begins downloading. Four dependencies install automatically:
| Package | Version |
| --------------------------------- | ------------------------------------------------------------------------- |
| `com.unity.ai.inference` | space.vars.dep\_ai\_inference\_version |
| `com.unity.nuget.newtonsoft-json` | space.vars.dep\_newtonsoft\_json\_version |
| `com.unity.ugui` | space.vars.dep\_ugui\_version |
| `com.unity.inputsystem` | space.vars.dep\_inputsystem\_version |
Wait for the progress bar in the bottom-right of the Unity Editor to complete before continuing.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
**Dependency conflict:** If your project already pins any of these four packages to an older version in `Packages/manifest.json`, the install will fail or produce a version mismatch. Open `Packages/manifest.json`, remove or update the conflicting version entries, then retry.
{% endhint %}
{% hint style="success" %}
**Installation complete** when the Convai SDK for Unity entry appears in the Package Manager list with a green checkmark and version space.vars.unity\_sdk\_version. You will also see a new **Convai** menu item in the Unity menu bar.
{% endhint %}
{% endtab %}
{% tab title="Asset Store" %}
{% stepper %}
{% step %}
#### Add the SDK to your Asset Store account
Open the [Unity Asset Store](https://assetstore.unity.com/) in your browser. Search for **Convai SDK for Unity** and open the listing. Click **Add to My Assets**, signing in with your Unity ID if prompted.
The button changes to **Open in Unity** when the asset has been added to your account.
{% endstep %}
{% step %}
#### Open Package Manager
In the Unity Editor menu bar, select **Window > Package Manager**.
{% endstep %}
{% step %}
#### Switch to My Assets
In the Package Manager window, click the packages source dropdown in the top-left (it shows **Packages: In Project** or similar) and select **My Assets**.
Your Asset Store library loads. Locate **Convai SDK for Unity** in the list.
{% endstep %}
{% step %}
#### Download and import
Select **Convai SDK for Unity** in the list. Click **Download**, then click **Import** once the download completes.
Unity imports the package and installs four dependencies automatically:
| Package | Version |
| --------------------------------- | ------------------------------------------------------------------------- |
| `com.unity.ai.inference` | space.vars.dep\_ai\_inference\_version |
| `com.unity.nuget.newtonsoft-json` | space.vars.dep\_newtonsoft\_json\_version |
| `com.unity.ugui` | space.vars.dep\_ugui\_version |
| `com.unity.inputsystem` | space.vars.dep\_inputsystem\_version |
Wait for the progress bar in the bottom-right of the Unity Editor to complete before continuing.
{% endstep %}
{% endstepper %}
To update the SDK to a newer version later, return to **My Assets** in the Package Manager, select the SDK, and click **Update**.
Installation is complete when the Convai SDK for Unity entry appears in the Package Manager list with version space.vars.unity\_sdk\_version. You will also see a new **Convai** menu item in the Unity menu bar.
{% endtab %}
{% endtabs %}
### Next steps
With the SDK installed, connect your project to Convai by entering your API key.
{% content-ref url="/pages/nLYDmLXfx19u9jY8DiYD" %}
[Configure the API key](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/configure-api-key)
{% endcontent-ref %}
# Configure the API key
Enter and validate your Convai API key for local development in the Unity Editor so a Convai character can authenticate while you build a scene.
The Convai SDK for Unity's **API Key** authentication mode reads an API key tied to your Convai account directly from the project's saved settings. Use this page to enter that key for local development in the Unity Editor — iterating on a scene, running sample scenes, or testing on a machine only you control.
{% hint style="warning" %}
API Key mode is for local development, not for a build you distribute. A player build produced in API Key mode contains your account API key, obfuscated but not encrypted, inside the shipped `ConvaiSettings` asset. Before you build anything you plan to ship, read [Authentication](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication) and switch to Auth Token mode.
{% endhint %}
{% stepper %}
{% step %}
#### Copy your API key
Log in to your [Convai dashboard](https://convai.com), navigate to **Account Settings**, and copy your API key.
{% endstep %}
{% step %}
#### Open the Credentials section
In the Unity Editor menu bar, open **Convai > Settings** (or **Edit > Project Settings > Convai SDK**), then select the **Credentials** section. Leave **Auth Mode** set to **API Key**, its default.
{% endstep %}
{% step %}
#### Paste and validate the API key
Paste your API key into the **API Key** field, then select **Validate & Save**. Convai checks the key and, if it accepts the key, the SDK saves it to the project.
The status badge next to the button reports the result: **Key valid** when Convai accepts the key, or an error message such as **Key invalid** when it does not.
{% endstep %}
{% step %}
#### Verify the key is accepted
Run **GameObject > Convai > Validate Scene Setup**. A missing API key appears as a warning in the validator dialog. If no API key warning appears, your key is configured correctly.
