Quick Start
A step-by-step walkthrough of your first working Convai Action — from adding components to testing a live command in Play Mode.
Get Your First Action Working
This guide walks you through a complete, working example: a character that moves to a crate when the player asks. You will add the required components, define one action, register one object target, and test everything in Play Mode.
Prerequisites
A Unity scene with a
ConvaiCharactercomponent already set up and working (the character should respond to speech before you add Actions).Your Convai API key is configured in Tools → Convai → Configuration.
A GameObject in your scene to use as the target (a cube or any object works — rename it
Cratefor this guide).
Step-by-Step Setup
Add ConvaiActionConfigSource
Select your NPC's GameObject in the Hierarchy. In the Inspector, click Add Component and search for Convai Action Config Source.
This component is where you define available actions and register scene objects as targets.

Add ConvaiActionDispatcher
With the same NPC GameObject selected, click Add Component again and search for Convai Action Dispatcher.
This component receives action commands from the Convai backend and runs the matching executor.
Both components must be on the same GameObject as ConvaiCharacter. The dispatcher will not work otherwise.

Add TransformMoveToActionExecutor
Still on the same NPC GameObject, click Add Component and search for Transform Move To Action Executor.
This executor moves the character to a target by instantly snapping its position. It is used here to keep the setup simple.
Transform Move To Action Executor teleports the character instantly with no animation or pathfinding. It is intended for prototyping only. For production use, replace it with NavMesh Move To Action Executor or a custom executor that uses your game's movement system.

Define the "Move To" Action
In the Convai Action Config Source component in the Inspector:
Under Action Definitions, click the + button to add a new entry.
Set Action Name to
Move To.Set Target Requirement to
Object.Drag the
Transform Move To Action Executorcomponent (from the same GameObject) into the Executor field.
Leave Timeout Seconds at 0 (no timeout).
Your definition should look like this:
Action Name
Move To
Target Requirement
Object
Executor
TransformMoveToActionExecutor (drag from Inspector)
Timeout Seconds
0

Register the Crate as an Object Target
Still in Convai Action Config Source:
Under Actionable Objects, click the + button.
Set Name to
Crate.Set Description to
A wooden crate sitting on the warehouse floor.Drag your
CrateGameObject from the Hierarchy into the Game Object Reference field.
The Description tells the Convai backend what this object is and helps the AI resolve vague references like "it" or "that thing." Write it like a short sentence describing the object in context. See Attention & Reference Grounding for tips.

Test in Play Mode
Press Play. Talk to your character (or use the Convai text input):
"Go to the crate." "Move to the crate." "Walk over to the crate."
The character's position should snap to the crate's location.
If the character moves to the crate, your Action system is working correctly. The ConvaiActionDispatcher received the command, resolved "Crate" as a target, and called TransformMoveToActionExecutor.
What Just Happened
When you spoke to the character, the following occurred:
Your speech was sent to Convai Cloud.
The backend recognized the intent and selected the
Move Toaction withCrateas the target.ConvaiActionDispatcherreceived the command, looked up yourMove Todefinition, and resolvedCrateto the scene GameObject.TransformMoveToActionExecutorran and snapped the character's position to the crate.
All of this happened automatically — no code required.
What's Next
Now that you have a working action, explore the rest of the documentation:
Configuring Actions — Learn how to add more actions, use character targets, and understand all available options.
Action Executors — Replace
TransformMoveToActionExecutorwith a production-ready executor likeNavMeshMoveToActionExecutor.Writing Custom Executors — Build any behavior that isn't covered by the built-in executors.
Conclusion
In a few steps, you set up a complete action pipeline: a character that moves to a scene object in response to natural conversation. From here, you can add more actions, swap in more sophisticated executors, and build complex multi-step behaviors — all without changing how the character communicates.
Last updated
Was this helpful?