> 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/narrative-design/narrative-triggers.md).

# Narrative triggers

Narrative triggers advance a character's story graph from one section to the next. `UConvaiChatbotComponent` exposes two Blueprint functions for firing triggers and one event for reacting to section changes. If you have not invoked a trigger before, complete [Narrative design quick start](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/narrative-design/narrative-design-quick-start.md) first.

### Choose the right function

| Goal                                              | Function                            | What it sends                                   |
| ------------------------------------------------- | ----------------------------------- | ----------------------------------------------- |
| Advance the graph using a dashboard trigger name  | **Invoke Narrative Design Trigger** | `trigger-message` with `trigger_name`           |
| Stage a runtime message as conversational context | **Invoke Speech**                   | Dynamic context event through `AddContextEvent` |

Use **Invoke Narrative Design Trigger** when the transition target is known at design time and the trigger name is a fixed string in the dashboard. Use **Invoke Speech** when the message is assembled at runtime, when the character should say a scripted line, or when you want Convai to process game-state text as conversational context rather than match a dashboard trigger name.

**On Narrative Section Received** fires only after Convai confirms a section change through a `BTResponse` packet. It does not fire when either function is called.

### Invoke a named trigger

**Invoke Narrative Design Trigger** (`InvokeNarrativeDesignTrigger`) sends a `TriggerName` string to Convai through `SendTriggerMessage`. Convai matches the name against outbound triggers configured for the current section in the dashboard.

| Input                  | Type      | Description                                                                        |
| ---------------------- | --------- | ---------------------------------------------------------------------------------- |
| `TriggerName`          | `FString` | The trigger name. Must match the dashboard configuration exactly (case-sensitive). |
| `InGenerateActions`    | `bool`    | Present in the Blueprint signature. Not applied in the current plugin source.      |
| `InReplicateOnNetwork` | `bool`    | Present in the Blueprint signature. Not applied in the current plugin source.      |

If `TriggerName` is empty, the plugin logs `Invoke Narrative Design Trigger: TriggerName is missing` and returns without sending a trigger.

{% hint style="warning" %}
Copy the trigger name from the dashboard character-for-character. A mismatch between the Blueprint string and the dashboard `trigger_name` produces no section change.
{% endhint %}

### Invoke a dynamic context message

**Invoke Speech** (`ExecuteNarrativeTrigger`) stages a dynamic context event through `AddContextEvent` with `EC_RunLLMOption::Always`. It does not send a `trigger-message` packet and does not queue in `PendingTriggers`.

| Input                  | Type      | Description                                                                   |
| ---------------------- | --------- | ----------------------------------------------------------------------------- |
| `TriggerMessage`       | `FString` | The message string staged as a context event.                                 |
| `InGenerateActions`    | `bool`    | Present in the Blueprint signature. Not applied in the current plugin source. |
| `InReplicateOnNetwork` | `bool`    | Present in the Blueprint signature. Not applied in the current plugin source. |

Use a plain `TriggerMessage` when the character should process the message as context, such as `Player completed the evacuation drill with 82 percent accuracy`. Wrap the message in `<speak>` tags when the character should say the text directly, such as `<speak>Attention: the evacuation route is now open.</speak>`.

If Convai determines a section change is appropriate, **On Narrative Section Received** still fires through the same `BTResponse` path.

If `TriggerMessage` is empty, the plugin logs `Invoke Speech: TriggerMessage is missing` and returns without staging an event.

### Handle the section change event

Bind **On Narrative Section Received** (`OnNarrativeSectionReceivedEvent`) on the chatbot component to react when Convai advances to a new section.

| Output pin           | Type                       | Description                                     |
| -------------------- | -------------------------- | ----------------------------------------------- |
| `ChatbotComponent`   | `UConvaiChatbotComponent*` | The component that received the section update. |
| `NarrativeSectionID` | `FString`                  | The `section_id` of the new active section.     |

To bind in Blueprint: drag the `UConvaiChatbotComponent` reference into the Event Graph, then select **Assign On Narrative Section Received** from the context menu.

When a specific section should run custom Blueprint logic, copy that section's `section_id` from **Narrative Design** in the Convai dashboard. Use the ID value, not the section name shown in the graph. In the bound event, compare the incoming `NarrativeSectionID` with the copied value. If the strings match, run the Blueprint logic for that section, such as opening a door, enabling a widget, or starting an assessment timer.

### Pending named triggers

When **Invoke Narrative Design Trigger** is called and the session is not connected, the plugin stores the call in `PendingTriggers`. Pending triggers replay in order after the session connects and the dynamic context flush completes.

{% hint style="warning" %}
Calling `Reset Dynamic Context` clears `PendingTriggers`. If the component is destroyed before the session reconnects, queued triggers are also discarded. **Invoke Speech** does not use the pending trigger queue.
{% endhint %}

### Session readiness

`bAutoInitializeSession` on `UConvaiChatbotComponent` defaults to `true`. When enabled, the component calls `StartSession` on **Begin Play**. Named triggers called before the session connects queue in `PendingTriggers` and replay once the connection is open.

If `bAutoInitializeSession` is `false`, call `StartSession` explicitly before you expect triggers to send immediately. You can also bind **On Character Data Loaded** (`OnCharacterDataLoadEvent_V2`) and invoke triggers from that event when you need confirmation that character data has loaded.

### Next steps

{% content-ref url="/pages/WlLowI3BqDYQNs4lfQM4" %}
[Template keys](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/narrative-design/template-keys.md)
{% endcontent-ref %}

{% content-ref url="/pages/7L5OLPdjT22ynoNiU7gD" %}
[Narrative design Blueprint reference](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/narrative-design/narrative-design-blueprint-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/Y84uFwti8p03e69iFquR" %}
[Narrative design usage examples](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/narrative-design/narrative-design-usage-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/narrative-design/narrative-triggers.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.