> 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/embodiment/conversation-flow/configure.md).

# Configure conversation flow

Add the Conversation Flow module to a character, or let Convai auto-create it, then assign a profile to tune its timing.

Add `ConvaiConversationFlowController` to a character yourself, or let Convai add it automatically, then assign a `ConvaiConversationFlowProfile` to change how quickly it moves between dialogue states. Use this page once you want direct control over the module's timing instead of relying on its built-in defaults.

***

### Prerequisites

* A `ConvaiCharacter` in your scene.
* Optional but recommended: an embodiment module that reads dialogue state — Gaze, Body Animation, Body Language, or Emotion — already added, so tuning Conversation Flow has a visible effect. Conversation Flow alone changes nothing about how the character looks; it only tracks state for the other modules to read.

{% hint style="info" %}
You rarely need this page for its first step. If your character already has Body Animation with `Auto Create Conversation Flow` enabled (the default), Convai adds the controller for you the first time it is needed. Skip to [Assign a profile](#assign-a-profile) if that is your situation.
{% endhint %}

***

### Add the controller

{% stepper %}
{% step %}

#### Select the character

In the Hierarchy, select the `GameObject` that carries the `ConvaiCharacter` component.
{% endstep %}

{% step %}

#### Add the Conversation Flow component

In the Inspector, select **Add Component**, then **Convai > Embodiment > Conversation Flow**. This adds `ConvaiConversationFlowController`.

Convai also adds the shared infrastructure the module needs — an `EmbodimentContext` — automatically. You do not add this yourself.
{% endstep %}

{% step %}

#### Leave the profile unassigned to start

With no profile assigned, the component's **Profile** section shows an **Using SDK Defaults** notice and the controller runs on built-in timing values, which work. Assign a profile only once you want to change the pace.
{% endstep %}
{% endstepper %}

***

### Assign a profile

{% stepper %}
{% step %}

#### Create a profile asset

Select **Assets > Create > Convai > Embodiment > Conversation Flow Profile**. This creates a `ConvaiConversationFlowProfile` asset.
{% endstep %}

{% step %}

#### Assign it to the controller

Select the character and drag the profile asset onto the **Flow Profile** field in the component's **Profile** section.
{% endstep %}

{% step %}

#### Tune the timing fields

Open the profile asset and adjust its fields under **Transition**, **Dialogue Beats**, and **Energy** — for example, lower **Thinking Max Hold** for a character that should reply faster, or raise **Idle Return Delay** to keep the character attentive longer between turns. See [Conversation flow reference](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/conversation-flow/reference.md) for every field, its range, and its default.
{% endstep %}
{% endstepper %}

A profile asset can be shared across multiple characters. Editing it changes the timing for every character it is assigned to.

***

### Verify the setup

Enter Play mode, select the character, and expand the **Live** section on the `ConvaiConversationFlowController` component (or open **Convai > Embodiment Editor**, select the **Live** tab). Start a conversation and confirm **State** moves through `Listening`, `Thinking`, and `Speaking` as the conversation progresses, instead of staying on `Idle`.

{% hint style="success" %}
**Expected result:** **State** changes away from `Idle` shortly after you start speaking, and **Time In State** resets to `0.0s` each time it changes.
{% endhint %}

***

### Troubleshooting

If **State** never leaves `Idle`, or the character lingers in a state longer than the profile's values suggest it should, see [Troubleshoot conversation flow](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/conversation-flow/troubleshooting.md).

***

### Next steps

{% content-ref url="/pages/dNKfeP60DVcQ67D8f0EH" %}
[Conversation flow reference](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/conversation-flow/reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/V2kTQBCdj0QnnRAT8iKt" %}
[Troubleshoot conversation flow](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/conversation-flow/troubleshooting.md)
{% endcontent-ref %}

{% content-ref url="/pages/UbtubfC4hHpNPmgYPkJE" %}
[Embodiment presets](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/embodiment-presets.md)
{% endcontent-ref %}


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/conversation-flow/configure.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.