> 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-unreal-engine-plugin/features/character-actions/building-custom-action-handlers.md).

# Building custom action handlers

Custom action handlers are Blueprint functions or events on the NPC Actor that the plugin calls when a matching action name arrives in the queue. Declare the action on the chatbot, scaffold a handler in the character Blueprint, run your logic, then call `Handle Action Completion` so the queue can advance.

### Prerequisites

* Character actions are enabled on the chatbot. See [Character actions quick start](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/character-actions-quick-start.md).
* You know the action name you want to add matches the handler name exactly, including spaces.

### Declare the action template

{% stepper %}
{% step %}

#### Add an entry to the Actions array

Select the NPC Actor. Under **Convai | Actions > Environment > Actions**, click **+**.

Set **Name** to a unique verb phrase, for example `"Print"`. Set **Description** to a short hint for Convai, for example `"Print a debug message to the screen"`. Leave **Parameters** empty for a no-parameter action.
{% endstep %}

{% step %}

#### Compile the Blueprint

Click **Compile** on the character Blueprint so the new action template is saved before you wire the handler.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Keep action names and descriptions short. Long descriptions increase the context sent to Convai without improving behavior. Leave **Description** empty when the action name is self-explanatory.
{% endhint %}

### Scaffold the handler with Create Convai Action Handler

The `ConvaiEditor` module adds a **Create Convai Action Handler** entry to the Blueprint graph context menu. Use it to generate a correctly named handler with the right parameter type.

{% stepper %}
{% step %}

#### Open the character Blueprint Event Graph

Open the NPC Actor Blueprint that owns the `Convai Chatbot` component.
{% endstep %}

{% step %}

#### Create the handler

Right-click in the **Event Graph** and search for **Create Convai Action Handler**.

Select the action you added (for example `Print`), choose **Event (on Event Graph)** or **Function (new function graph)**, and confirm creation. The utility adds a handler named exactly like the action, with one `FConvaiResultAction` input, and wires a `Handle Action Completion` call at the end.
{% endstep %}

{% step %}

#### Add handler logic between the event and completion

Connect your behavior between the event pin and `Handle Action Completion`. For a `Print` action, add a **Print String** node with a literal message such as `"This is the print action"`.
{% endstep %}
{% endstepper %}

You can also create handlers manually: add a **Custom Event** with the exact action name and one `FConvaiResultAction` parameter. The plugin dispatches by name — see [How character actions work](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/how-character-actions-work.md).

### Handle Action Completion

Every handler must call `Handle Action Completion` on the `Convai Chatbot` component when the action finishes, succeeds, fails, or is interrupted. Without this call, the queue stalls and later actions never run.

{% hint style="info" %}
For most handlers, only `IsSuccessful` needs to change. The remaining parameters are advanced — leave them at their defaults until you need spoken feedback from the character.
{% endhint %}

| Parameter        | Default | Purpose                                                                                     |
| ---------------- | ------- | ------------------------------------------------------------------------------------------- |
| `IsSuccessful`   | `true`  | `true` dequeues the current action and starts the next. `false` clears the remaining queue. |
| `bAutoReport`    | `true`  | When `true`, sends a default outcome message to Convai.                                     |
| `ShouldRespond`  | `Never` | Controls whether Convai speaks about the outcome.                                           |
| `AdditionalNote` | `""`    | Optional text appended to the auto-generated message. Advanced pin.                         |
| `Delay`          | `0.0`   | Seconds to wait before the next action starts. Advanced pin.                                |

#### When to change Auto Report

For simple actions that need no spoken follow-up, leave `bAutoReport` at its default or set `ShouldRespond` to `Never`. The character still receives silent context about the outcome.

Disable or tune `bAutoReport` when:

* The action is a debug or UI-only step (for example `Print`).
* You want Convai to acknowledge a failure aloud — set `ShouldRespond` to `Always` and provide an `AdditionalNote`.

#### Completion on every exit path

Wire `Handle Action Completion` on all branches:

* Success path after the action finishes.
* Failure path when preconditions are not met.
* Interrupted path when a latent action (animation montage, timer, move) is cancelled.

```
// Blueprint pseudocode — Print handler
Event Print(ActionData: FConvaiResultAction)
    Print String("This is the print action")
    HandleActionCompletion(
        IsSuccessful = true,
        bAutoReport = true,
        ShouldRespond = Never
    )
```

### AbortActionSequence

When a handler cannot recover — a target Actor was destroyed, a montage failed to play, preconditions are permanently unmet — call `AbortActionSequence` instead of retrying with `Handle Action Completion(false)`.

| Parameter       | Default | Purpose                                                                                        |
| --------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `EventText`     | `""`    | Description of what failed. Empty causes a silent abort.                                       |
| `ShouldRespond` | `Auto`  | How Convai should react. Use `Always` when the character should acknowledge the failure aloud. |

### Observe actions with On Actions Received

Bind to **On Actions Received** on the chatbot component to log or debug the raw action sequence. This delegate does not replace name-based dispatch — the plugin still calls matching handlers automatically.

```
// Blueprint pseudocode
On Actions Received(
    ChatbotComponent: UConvaiChatbotComponent,
    InteractingPlayerComponent: UConvaiPlayerComponent,
    SequenceOfActions: TArray<FConvaiResultAction>
)
```

Use this delegate for diagnostics, not as a replacement for per-action handlers.

### Example: Open Door handler

```
// Blueprint pseudocode
Event Open Door(ActionData: FConvaiResultAction)
    TargetEntry = GetParamAsRef(ActionData, "target")
    DoorActor = TargetEntry.Ref

    if DoorActor is not valid:
        AbortActionSequence(
            EventText = "The door target is missing",
            ShouldRespond = Always
        )
        return

    Call OpenAnimation on DoorActor
    Delay 1.5 seconds

    HandleActionCompletion(
        IsSuccessful = true,
        bAutoReport = true,
        ShouldRespond = Never
    )
```

### Next steps

{% content-ref url="/pages/y5n6zO4nhEgGfJnXzGk4" %}
[Parameterized actions](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/parameterized-actions.md)
{% endcontent-ref %}

{% content-ref url="/pages/lEX58Owo3bAVjCGO0ezK" %}
[Actions Blueprint reference](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/KjK5RrpmmborH095i0oC" %}
[Character actions examples](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/character-actions/character-actions-examples.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-unreal-engine-plugin/features/character-actions/building-custom-action-handlers.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.