Built-in action handlers

Reference handler patterns for the four default Convai character actions, including parameters, completion rules, and Blueprint flow.

Every new Convai Chatbot component includes four pre-configured action templates: Move To, Follow, Stop Moving, and Wait For. These templates define the action names and parameters — you still need to implement the corresponding Blueprint events in your NPC character Blueprint. This page provides a copy-ready handler pattern for each action.

Choosing the right handler

Action	Parameters	Purpose	Completion model
Move To	destination (Reference)	Navigate to a registered object or character target	Completes when movement ends
Follow	character (Reference)	Start continuously following a registered character	Completes after the follow loop starts
Stop Moving	—	Cancel any in-progress movement	Completes immediately
Wait For	time in seconds (Number)	Pause the action queue for a duration	Completes after the delay

The movement handler patterns use AI Move To and require an AI Controller and Nav Mesh Bounds Volume. Wait For does not require navigation. If your NPC does not use Unreal's navigation system, replace the movement logic with your own approach and keep the same HandleActionCompletion pattern.

Move To

Navigates the NPC to a registered object. The destination parameter is a Reference type that resolves against the registered object name.

Parameter:

Name	Type	Description
destination	Reference (FConvaiObjectEntry)	The object the NPC should walk to. Resolved against the registered Objects and Characters lists (Objects searched first).

Blueprint handler:

Use Create Convai Action Handler (right-click in the Event Graph) to scaffold this event automatically, then replace the placeholder logic with the pattern below.

// Blueprint pseudocode
// Custom Event named "Move To" with one FConvaiResultAction input

Event Move To(ActionData: FConvaiResultAction)
    // Read and resolve the destination
    DestEntry = GetParamAsRef(ActionData, "destination")
    ResolveGoalLocation(
        Entry = DestEntry,
        SourceActor = Self,
        // outputs:
        TargetActor, ObjectActor, OutGoalComponent, Destination,
        OutAcceptanceRadius, UsesDestination,
        bSuccess, bAlreadyThere, bReachable,
        PathEnd, PathPoints, GoalTravelDistance, MovementPointIndex
    )

    // Guard: destination Actor must be alive
    if not bSuccess:
        AbortActionSequence(
            EventText = "Navigation target no longer exists",
            ShouldRespond = Always
        )
        return

    // Skip movement if already at the goal
    if bAlreadyThere:
        HandleActionCompletion(IsSuccessful = true)
        return

    // Wire both pins into one AI Move To — no branch needed
    AIMoveTo(
        Target = TargetActor,
        Destination = Destination,
        AcceptanceRadius = OutAcceptanceRadius
    )

    // Wait for OnMoveCompleted (bind to AIController.ReceiveMoveCompleted or use
    // a task/latent action), then call:
    HandleActionCompletion(IsSuccessful = true)

Key points:

• Wire Target Actor and Destination straight into one AI Move To node. No branch is needed: Target Actor is null exactly when the goal is a fixed location — a Movement Point won, or the entry references a component — so AI Move To falls through to Destination on its own.
• Resolve Goal Location with a live Source Actor also computes bOut Reachable, Out Path Points, and Out Goal Travel Distance, which you can use to bail out early when no NavMesh path exists. Out Movement Point Index reports which Movement Points entry won, or -1 when the object reference resolved the goal instead.
• AcceptanceRadius comes from the registered FConvaiObjectEntry (default 150 cm). Increase it for large objects or decrease it for precise sub-component targeting.

Follow

Starts a continuous follow behavior for a registered character. The follow timer or task can keep running after the action completes; call HandleActionCompletion(true) after the follow loop starts so future actions can dispatch.

Parameter:

Name	Type	Description
character	Reference (FConvaiObjectEntry)	The character to follow. Resolved against the registered Objects and Characters lists (Objects searched first).

Blueprint handler:

Use Create Convai Action Handler (right-click in the Event Graph) to scaffold this event automatically, then replace the placeholder logic with the pattern below.

// Blueprint pseudocode
// Custom Event named "Follow" with one FConvaiResultAction input

Event Follow(ActionData: FConvaiResultAction)
    TargetEntry = GetParamAsRef(ActionData, "character")

    if TargetEntry.Ref is None:
        AbortActionSequence(
            EventText = "Follow target not found",
            ShouldRespond = Always
        )
        return

    // Start a repeating timer (e.g., every 0.5s) that calls
    // AIMoveTo(Target = TargetEntry.Ref, AcceptanceRadius = 150.0)
    // Store the timer handle so Stop Moving can cancel it.

    // Complete the Follow action after the loop starts.
    // The timer/task keeps running until Stop Moving fires later.
    HandleActionCompletion(IsSuccessful = true)

Implementation note — polling timer:

A common approach is a Set Timer by Function Name node that re-issues AI Move To toward the target Actor every 0.5–1.0 seconds. Store the timer handle in a Blueprint variable, then call HandleActionCompletion(true) after the timer starts. When Stop Moving fires later, clear the timer and complete the stop action.

Alternatively, implement a BehaviorTree task that loops until an external signal is set, and signal it from the Stop Moving handler.

Stop Moving

Cancels any in-progress movement behavior and completes the current action. If Follow started a timer or task, Stop Moving should clear that timer or task and then call HandleActionCompletion(true) for the stop action.

Parameters: none

Blueprint handler:

Use Create Convai Action Handler (right-click in the Event Graph) to scaffold this event automatically, then replace the placeholder logic with the pattern below.

// Blueprint pseudocode
// Custom Event named "Stop Moving" with one FConvaiResultAction input

Event Stop Moving(ActionData: FConvaiResultAction)
    // Cancel the repeating follow timer
    ClearTimer(FollowTimerHandle)

    // Stop current movement immediately
    AIController.StopMovement()

    // Complete the Stop Moving action
    HandleActionCompletion(IsSuccessful = true)

The Blueprint Custom Event name must be Stop Moving (with a space) to match the default action name exactly. StopMoving (no space) will not dispatch.

---

Wait For

Pauses the action queue for a configurable number of seconds. After the delay, HandleActionCompletion advances the queue to the next action.

Parameter:

Name	Type	Description
time in seconds	Number (float)	The number of seconds to pause. Convai fills this value; guide it with a clear parameter description such as "A plain number of seconds, e.g. 3".

Blueprint handler:

Use Create Convai Action Handler (right-click in the Event Graph) to scaffold this event automatically, then replace the placeholder logic with the pattern below.

// Blueprint pseudocode
// Custom Event named "Wait For" with one FConvaiResultAction input

Event Wait For(ActionData: FConvaiResultAction)
    Seconds = GetParamAsNumber(ActionData, "time in seconds")

    // Guard: clamp to a sensible range
    Seconds = Clamp(Seconds, 0.1, 30.0)

    // Use Unreal's built-in Delay node (latent action)
    Delay(Duration = Seconds)

    // After the delay completes:
    HandleActionCompletion(IsSuccessful = true)

Implementation note — Delay node:

The built-in Delay Blueprint node is a latent action and works correctly here. If your handler logic is inside a function rather than a Custom Event, use a Set Timer by Event node instead (latent actions only work in event graphs, not in Blueprint functions).

---

Modifying the default actions

You can rename, remove, or extend any default action in the Actions array:

• Rename — change Name in the Details panel and rename the Blueprint Custom Event to match.
• Remove — select the entry in the Actions array and click the delete button. The Blueprint event becomes dead code but does not cause an error.
• Add a parameter — add an FConvaiActionParam entry to the Parameters array on the template. Update your handler to read the new parameter with GetParamAs*.

If you rename any of these action templates, rename the corresponding Blueprint Custom Event to match, including spaces. Unreal resolves handler names case-insensitively, but "Stop Moving" and "StopMoving" are different names.

---

Next steps

Building custom action handlersParameterized actionsCharacter actions examples