> 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/fetching-narrative-data.md).

# Fetching narrative data

The Convai Unreal Engine plugin exposes two async Blueprint nodes under **Convai|REST API** that retrieve narrative sections and triggers for a character from Convai. Use these nodes to validate trigger names before invoking them, populate dynamic UI, or pre-cache narrative data during a loading screen.

These nodes are optional. The normal story progression path is **Invoke Narrative Design Trigger** on `UConvaiChatbotComponent`, not fetch-and-invoke.

### Prerequisites

* The Convai Unreal Engine plugin is installed and the API key is configured. See [Configure your API key](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md).
* A valid `CharacterId` that matches the `CharacterID` on the target `UConvaiChatbotComponent`.
* Network access at the time the fetch node executes. Fetch nodes make HTTPS POST requests to Convai.

### Fetch Narrative Sections

**Convai Fetch Narrative Sections** is an async latent Blueprint node implemented by `UFetchNarrativeSectionsProxy`. It POSTs to `character/narrative/list-sections` and returns sections configured for that character in the dashboard.

| Pin                  | Direction     | Type                        | Description                                                                                                               |
| -------------------- | ------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `CharacterId`        | Input         | `FString`                   | The character ID to query. Must match the `CharacterID` on the target `UConvaiChatbotComponent`.                          |
| `On Success`         | Output (exec) | —                           | Fires when the HTTP request succeeds and the response is parsed into `FNarrativeSection` entries.                         |
| `On Failure`         | Output (exec) | —                           | Fires when activation validation fails, the response pointer is invalid, or the HTTP response is outside the `2xx` range. |
| `Narrative Sections` | Output        | `TArray<FNarrativeSection>` | The sections returned on success. Empty on failure.                                                                       |

**To add the node in Blueprint:**

1. Right-click the Event Graph and search for `Fetch Narrative Sections`.
2. Select **Convai Fetch Narrative Sections** under **Convai|REST API**.
3. Set the `CharacterId` input to the same value used by the `UConvaiChatbotComponent` you are working with.
4. Connect nodes to both **On Success** and **On Failure** execution pins.

### Fetch Narrative Triggers

**Convai Fetch Narrative Triggers** is an async latent Blueprint node implemented by `UFetchNarrativeTriggersProxy`. It POSTs to `character/narrative/list-triggers` and returns triggers configured across the character's narrative graph.

| Pin                  | Direction     | Type                        | Description                                                                                                               |
| -------------------- | ------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `CharacterId`        | Input         | `FString`                   | The character ID to query.                                                                                                |
| `On Success`         | Output (exec) | —                           | Fires when the HTTP request succeeds and the response is parsed into `FNarrativeTrigger` entries.                         |
| `On Failure`         | Output (exec) | —                           | Fires when activation validation fails, the response pointer is invalid, or the HTTP response is outside the `2xx` range. |
| `Narrative Triggers` | Output        | `TArray<FNarrativeTrigger>` | The triggers returned on success. Empty on failure.                                                                       |

Each `FNarrativeTrigger` in the result exposes `trigger_name`, `trigger_id`, `trigger_message`, and `destination_section` as `BlueprintReadOnly` fields. The `trigger_name` field is what you pass to **Invoke Narrative Design Trigger**.

### When to call fetch nodes

Call fetch nodes at load time, not repeatedly during gameplay:

* **Begin Play** — fetch before any trigger is invoked so the data is ready when gameplay starts.
* **Loading screen** — fetch in parallel with other load work while the player cannot interact with the character.
* **Editor utility Blueprints** — inspect a character's narrative graph in the Unreal Editor without opening the Convai dashboard.

{% hint style="warning" %}
Fetch nodes make an HTTPS request to Convai each time they are executed. Do not call them on Tick or in response to repeated gameplay events. Cache the result in a Blueprint variable and reuse it.
{% endhint %}

### Handle the results

On the **On Success** pin of **Convai Fetch Narrative Triggers**, iterate the `Narrative Triggers` array and extract each `trigger_name` into a `TSet<FString>` or Map variable. Before calling **Invoke Narrative Design Trigger**, check that the intended name is in the set.

On the **On Success** pin of **Convai Fetch Narrative Sections**, iterate `Narrative Sections` and use each `section_id` and `section_name` to populate a dropdown or debug overlay.

For a complete trigger-validation recipe, see [Narrative design usage examples](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/narrative-design/narrative-design-usage-examples.md#fetch-triggers-to-validate-names-before-invoking).

### Verify the fetch

After running a fetch node in Play In Editor:

1. Confirm the **On Success** execution pin fires (not **On Failure**).
2. Inspect `Narrative Sections` or `Narrative Triggers` — the array should contain entries for the character you queried.
3. If **On Failure** fires, check the **Output Log** for `ConvaiNarrativeHTTP` messages. See [Troubleshoot narrative design](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/narrative-design/troubleshoot-narrative-design.md).

{% hint style="info" %}
If the HTTP request succeeds but the response array cannot be parsed into narrative structs, the fetch proxy may return without firing **On Success** or **On Failure**. If a latent node appears to hang, check the **Output Log** for `ConvaiNarrativeHTTP` and retry after confirming the character has narrative data in the dashboard.
{% endhint %}

### Next steps

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