> 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/features/narrative-design/template-keys-dynamic-narrative-variables.md).
# Configure narrative template keys
Template keys are runtime key-value pairs that fill placeholders in your character's narrative objectives. Define placeholders in the [Convai dashboard](https://convai.com) using curly-brace syntax — for example, `{PlayerName}` or `{CurrentTask}` — and the SDK sends the actual values from Unity at runtime, so the character can reference them naturally in conversation. A single narrative graph can then serve many sessions with different participants or dynamic state without editing the graph each time.
### Define keys in the Inspector
Open `ConvaiNarrativeDesignManager` in the Inspector and expand the **Template Keys** foldout.
Click **+** to add an entry. Each entry has two fields:
| Field | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Key** | The placeholder name, exactly as written in the narrative design section objective (case-sensitive, without the curly braces). |
| **Value** | The initial value. You can override this at runtime from code. |
Template Keys foldout in ConvaiNarrativeDesignManager.
Keys defined in the Inspector are synced to the internal controller on `Awake` and sent to Convai automatically when the session opens. You do not need to call anything manually to ensure delivery.
In Play Mode, the Inspector shows a **Send to Server** button that immediately calls `SendTemplateKeysUpdate()`. This is useful for testing value changes mid-session without writing code.
### Update keys at runtime
Use any of the following methods on `ConvaiNarrativeDesignManager` to update keys from code:
**Update a single key:**
```csharp
narrativeManager.UpdateTemplateKey("PlayerName", "Alex");
```
**Update and send immediately (one call):**
```csharp
narrativeManager.UpdateAndSendTemplateKey("ScenarioPhase", "Handwashing");
```
Use `UpdateAndSendTemplateKey` when a key change should take effect on the character's very next response.
**Update multiple keys at once:**
```csharp
narrativeManager.UpdateTemplateKeys(new Dictionary
{
{ "PlayerName", "Alex" },
{ "Department", "Facilities" },
{ "CompletedSteps", "3" }
});
narrativeManager.SendTemplateKeysUpdate();
```
**Read the current key dictionary:**
```csharp
Dictionary current = narrativeManager.GetTemplateKeys();
```
### How keys are sent
```mermaid
flowchart TD
A["UpdateAndSendTemplateKey(key, value)"] --> B[UpdateTemplateKey\nupdates _templateKeys list + Controller]
B --> C[SendTemplateKeysUpdate\nSyncTemplateKeysToController]
C --> D[Controller.SendTemplateKeysUpdate\nfires OnTemplateKeysUpdateRequested]
D --> E[ConvaiCharacter.NarrativeDesign.SetTemplateKeys]
E --> F{IsInConversation?}
F -- Yes --> G[ConnectionService.UpdateTemplateKeys\nsent immediately]
F -- No --> H[_hasPendingTemplateKeySync = true\nqueued for FlushPending]
H --> I[Session opens → FlushPending\nkeys sent automatically]
```
If the character disconnects and reconnects, the SDK calls `MarkPendingReplayAfterDisconnect` internally so the latest key values are re-sent on the next connection. You never need to re-send keys manually after a reconnect.
### Key naming rules
| Rule | Example |
| ------------------------------------------------------------- | ---------------------------------------------------------------- |
| Must match the dashboard placeholder exactly (case-sensitive) | Dashboard: `{playerName}` → Key: `playerName` (not `PlayerName`) |
| No leading or trailing whitespace | `"PlayerName"` ✓ — `" PlayerName"` ✗ |
| No empty key string | `""` is silently ignored |
| Values can be empty strings | Key `"OptionalField"` with value `""` is valid |
**Good key names:**
| Key | Value example |
| ---------------------- | ------------- |
| `PlayerName` | `"Maria"` |
| `ScenarioLevel` | `"Advanced"` |
| `CompletedCheckpoints` | `"4"` |
| `SessionStartTime` | `"09:15"` |
**Problematic key names:**
| Key | Problem |
| --------------- | ------------------------------------------------------------------------------------------------ |
| `player name` | Space in name — will not match `{player name}` placeholders if the dashboard uses `{playerName}` |
| `"PlayerName "` | Trailing space — silent mismatch |
| `""` | Empty — ignored |
{% hint style="danger" %}
Template key values are sent as plain strings over the network and may appear in the character's dialogue. Do not include passwords, personal identification numbers, API secrets, or any other sensitive data in template key values.
{% endhint %}
### Set keys on the character directly
If you are working without a `ConvaiNarrativeDesignManager`, you can set template keys directly through the character API:
```csharp
ConvaiCharacter character = GetComponent();
// Single key
character.NarrativeDesign.SetTemplateKey("PlayerName", "Alex");
// Multiple keys
character.NarrativeDesign.SetTemplateKeys(new Dictionary
{
{ "PlayerName", "Alex" },
{ "Department", "Engineering" }
});
```
The character API and the Manager API both converge on the same `ConnectionService.UpdateTemplateKeys` call internally. You can use either path in the same project, but avoid calling both paths for the same key in the same frame, as this may send redundant updates.
### Next steps
{% content-ref url="/pages/ShMEkDz5iXv32f3SAnZ6" %}
[Narrative design scripting reference](/api-docs/plugins-and-integrations/convai-unity-sdk/features/narrative-design/scripting-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:
```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/features/narrative-design/template-keys-dynamic-narrative-variables.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.