LogoLogo
PlaygroundVideosBlogPricing
  • Welcome
  • Convai Playground
    • Playground Walkthrough
    • Get Started
    • Character Creator Tool
      • Create Character
      • Language and Speech
      • Knowledge Bank
      • Personality and Style
      • State of Mind
      • Memory
      • Actions
      • Narrative Design
      • Character Versioning
    • F.A.Q
  • Plugins & Integrations
    • Introduction
    • Unity Plugin
      • Pre-Requisites
      • Compatibility
      • Downloads
        • Limitations of WebGL Plugin
      • Setting Up Unity Plugin
      • Troubleshooting Guide
        • Disable Assembly Validation
        • Missing Newtonsoft Json
        • Microphone Permission Issues
        • Default Animations Incompatibility
        • Animations have Facial Blendshapes
        • Jaw Bone in Avatar is not Free
        • macOS Permission Issues
      • Creating a Convai Powered Scene from Template
      • Importing Ready Player Me (RPM) Characters
      • Importing Custom Characters
      • Adding Actions to your Character
      • Adding Lip-Sync to your Character
      • Adding Narrative Design to your Character
        • Narrative Design Keys
      • Adding NPC to NPC Conversation
      • Adding Scene Reference and Point-At Crosshairs
      • Utilities
        • Character Emotion
        • Player Data Container
        • Long Term Memory
        • Language Support
        • Managing sessionID Locally
        • Transcript UI System
        • Pre-built UI Prefabs
        • Input Management
        • Notification System
        • Settings Panel
        • Dynamic Information Context
      • Building For Supported Platforms
        • Building for iOS/iPadOS
        • Building for WebGL
        • Convai XR
          • Building for VR
            • VR Automatic Installation
            • VR Manual Installation
          • Building for MR
            • MR Automatic Installation
            • MR Manual Installation
          • Building for AR
          • Interacting with XR UI Elements
        • Building for macOS Universal apps
      • Changelogs
      • Tutorials
        • Narrative Design
        • NPC2NPC
    • Unreal Engine
      • Supported Platforms
      • Installation
      • Guides
        • Dynamic Environment Info
        • Change AI Character Movement Speed
        • Integration with Pixel Streaming
        • Adjust Interaction Radius
        • Creating MetaHuman Characters
          • Adding MetaHuman
          • Adding LipSync to MetaHuman (From plugin version 3.0.0 or later )
          • Change the Parent Class for MetaHuman
          • Change the parent class for Player.
          • Adding LipSync to MetaHuman (Deprecated)
        • Creating ReadyPlayerMe Characters
          • Download Plugins
          • Adding ReadyPlayerMe Character
          • Change the parent class for Player.
        • Creating Reallusion Characters
          • Creating a Reallusion Character
          • Importing Reallusion character and setting up the Convai plugin
          • Binding objects to Reallusion Character
        • Event-Aware Convai Characters
        • Operations Based on the Presence of Certain Words
        • Narrative Design
          • Narrative Design Trigger
          • Narrative Design Keys
        • Actions Guide
          • Stage 1: Default Actions
            • Moves To
            • Follows
          • Stage 2: Custom Actions
            • Simple actions
            • Adding Descriptions to Actions
          • Stage 3: Custom Actions with Single Parameter
          • Main Character and Attention Object
        • Customization
          • Push to Talk
          • Alter Character Response Audio Rate
        • Speech To Text Transcription
        • Enable Multiplayer Support
        • 3D Chat Widget
        • Long Term Memory
        • Saving and Loading Session
      • Blueprints Reference
        • Convai Player
        • Convai Chatbot
        • Convai Environment
        • Convai Object Entry
        • Convai Result Action
        • Convai Extra Params
        • Speech To Text
        • Text To Speech
        • Utility Functions
      • Troubleshoot Guide
        • Missing Unreal Engine Tool Set in Microsoft Visual Studio Toolchain
        • Convai Module Not Found
        • MetaHuman Plugin Conflict
        • Failure to Load Character IDs
      • Microphone Settings
        • Set Audio Gain
        • Set Microphone
        • Microphone test
        • List Microphone Devices
      • Mac Microphone Permission: Required for UE 5.0 and 5.3
      • Guides V2 (Under Development)
        • Getting Started
          • Installation
          • Simple Talking Cube
          • Adding Premade Chat and Settings UI
    • Web Plugin
      • PlayCanvas Plugin
        • Adding External Script
        • First Person View
        • Adding characters to scene
        • Character Animations
        • Convai Integration
        • Chat Overlay
      • Convai Web SDK
        • Getting Started
        • Facial Expressions
        • Actions
      • JavaScript Chat UI SDK
        • Getting Started
        • ChatBubble Props
      • Narrative Design Guide
        • Narrative Design Triggers
        • Narrative Design Keys
      • GLB Characters for Convai
      • GLB/FBX animations for Convai
    • Modding Framework
      • Modding Cyberpunk 2077
    • Other Integrations
      • Roblox
        • Sample Game 1
        • Sample Game 2
        • Code Example
          • Character Conversation API
      • Discord
        • Create a Discord Bot
        • Hosting Discord Bot from Personal Server
        • Hosting Discord Bot from Replit
      • Omniverse Extension
      • Third-Party API Integrations
        • ElevenLabs API Integration
    • Convai Pixel Streaming Embed
      • Whitelisting & Publishing an Experience
      • React Typescript
      • ReactJS (JavaScript)
      • Vanilla JavaScript (ES Modules)
      • CDN (UMD Script)
      • On Premise Deployment
      • API Reference
  • Reference
    • Core API Reference
      • Character Base API
      • Interaction API
      • Core AI Setting API
      • Backstory API
      • Chat History API
      • Knowledge Bank API
      • Narrative Design API
      • Action API
      • Language List API
      • Voice List API
      • Character List API
      • Evaluation API
Powered by GitBook
On this page
  • Toggle Narrative Design
  • Create Section
  • Edit Section
  • Get Section
  • List Sections
  • Delete Section
  • Create Trigger
  • Update Trigger
  • Delete Trigger
  • Get Trigger
  • List Triggers

Was this helpful?

  1. Reference
  2. Core API Reference

Narrative Design API

The page list all the APIs needed to interact Narrative Design

This API is accessible with all plans.

Toggle Narrative Design

POST https://api.convai.com/character/toggle-is-narrative-driven

Enable/Disable the Narrative Graph for your character.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

character_id

String

Id of your character.

is_narrative_driven

Bool

Set it to true or false, to enable disable Narrative Graph.

{"STATUS": "Successful"}
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/toggle-is-narrative-driven"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "character_id": "<Your-Character-Id>",
    "is_narrative_driven": True
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
curl -X POST "https://api.convai.com/character/toggle-is-narrative-driven" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{"character_id": "<Your-Character-Id>", "is_narrative_driven": true}'

Create Section

POST https://api.convai.com/character/narrative/create-section

Create new section for your Character.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

character_id

String

Id of your character.

objective

String

Section Objective

section_name

String

Name of the Section.

updated_character_data

Json

*Ignore* Field is not used.

behavior_tree_code

String

*Ignore* Field is not used.

bt_constants

String

*Ignore* Field is not used.

{
    "section_id": "<New-Section-Id>"
}
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/narrative/create-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "character_id":"<Your-Character-Id>",
    "objective":"Section Objective",
    "section_name":"SectionName",
    "updated_character_data":{},
    "behavior_tree_code":"",
    "bt_constants":""
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
curl -X POST "https://api.convai.com/character/narrative/create-section" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "objective": "Section Objective",
         "section_name": "SectionName",
         "updated_character_data": {},
         "behavior_tree_code": "",
         "bt_constants": ""
     }'

Edit Section

POST https://api.convai.com/character/narrative/edit-section

Edit section for your Character. You would send all the fields that you want to update for a section updated_character_data json. Following are the valid key.

  • "section_name"

  • "objective"

  • "decisions": This is a list of json. Each entry in the list should have following format.

    {
        "criteria":"Decision Criteria",
        "next_section_id":"ID of the section to transition"
    }

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

character_id

String

Id of your character.

updated_character_data

Json

Contains fields that are updated.

section_id

String

Id of the section to update.

{
    "status": "success",
    "section_id": "<Section-Id>",
    "updated_data": {
        "objective": "Some new objective."
    }
}
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/narrative/edit-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "character_id":"<Your-Character-Id>",
    "section_id":"<Section-Id->",
    "updated_data":{
        "decisions":[
            {"criteria":"User agrees to take tour.", "next_section_id":"b9d7f568-7d06-11ef-be6a-42010a7be011"}
        ],  
        "objective":"Offer user tour of a Museum.",
        "section_name":"Welcome Section"
    }   
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
curl -X POST "https://api.convai.com/character/narrative/edit-section" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "section_id": "<Section-Id->",
         "updated_data": {
             "decisions": [
                 {
                     "criteria": "User agrees to take tour.",
                     "next_section_id": "b9d7f568-7d06-11ef-be6a-42010a7be011"
                 }
             ],
             "objective": "Offer user tour of a Museum.",
             "section_name": "Welcome Section"
         }
     }'

Get Section

POST https://api.convai.com/character/narrative/get-section

Get details for a particular narrative section of your Character.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

character_id

String

Id of your character.

section_id

String

Id of the section to fetch.

{
   "character_id": "<Your-CharacterId>",
   "section_id": "<Your-SectionId>",
   "objective": "Offer user tour of History Museum.",
   "decisions": [{"criteria": "User agrees to take tour.", "next_section_id": "12345568-7890-1123-4456-424242424242"}],
   "parents": null,
   "updated_character_data": {},
   "bt_constants": "",
   "behavior_tree_code": "",
   "section_name": "Welcome Section",
   "triggers": null,
   "node_position": []
}
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/narrative/get-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "character_id":"<Your-Character-Id>",
    "section_id":"<Section-Id->", 
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
curl -X POST "https://api.convai.com/character/narrative/get-section" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
           "character_id": "<Your-Character-Id>",
           "section_id": "<Section-Id->"
         }'

List Sections

POST https://api.convai.com/character/narrative/list-sections

List details of all narrative sections for a given character.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

character_id

String

Id of your character.

[
  {
    "character_id": "<Your-Character-Id>",
    "section_id": "123456789-7ddd-dddd-bbbb-424242424242",
    "objective": "",
    "decisions": null,
    "parents": null,
    "updated_character_data": {},
    "bt_constants": "",
    "behavior_tree_code": "",
    "section_name": "section 1",
    "triggers": null,
    "node_position": []
  },
  {
    "character_id": "<Your-Character-Id>",
    "section_id": "100000789-7ddd-dddd-bbbb-42424242424",
    "objective": "Offer user tour of History Museum.",
    "decisions": [
      {
        "criteria": "User agrees to take tour.",
        "next_section_id": "123456789-7ddd-dddd-bbbb-424242424242"
      }
    ],
    "parents": null,
    "updated_character_data": {},
    "bt_constants": "",
    "behavior_tree_code": "",
    "section_name": "Welcome Section",
    "triggers": null,
    "node_position": []
  }
]
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/narrative/list-sections"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "character_id":"<Your-Character-Id>",
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
curl -X POST "https://api.convai.com/character/narrative/list-sections" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
           "character_id": "<Your-Character-Id>"
         }'

Delete Section

POST https://api.convai.com/character/narrative/delete-section

Delete a narrative section of your Character.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

character_id

String

Id of your character.

section_id

String

Id of the section to delete.

{"STATUS": "Successful"}
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/narrative/delete-section"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "character_id":"<Your-Character-Id>",
    "section_id":"<Section-Id->", 
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
curl -X POST "https://api.convai.com/character/narrative/delete-section" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "section_id": "<Section-Id->"
     }'

Create Trigger

POST https://api.convai.com/character/narrative/create-trigger

Create a new Trigger for your Character.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

character_id

String

Id of your character.

trigger_name

String

Name of the trigger. Must be unique for a character.

trigger_message

String

Message for the trigger. Commonly tell the event for which the Trigger is invoked. E.g. User entered the scene.

desgination_section

String

Destination section-id for this trigger. Do not pass this field if you don't want to connect Trigger to any section.

{
    "character_id": "<Your-Character-Id>,
    "trigger_id": "<ID-Of-The-Newly-Created-Trigger>",
    "trigger_name": "StartTrigger",
    "trigger_message": "User has entered the museum.",
    "destination_section": "<Destination-Section-ID>",
    "node_position": []
}
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/narrative/create-trigger"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "character_id":"<Your-Character-Id>",
    "trigger_message":"User has entered the museum.",
    "trigger_name":"StartTrigger",
    "destination_section": "<Destination-Section-ID-to-connect-to>"
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
curl -X POST "https://api.convai.com/character/narrative/create-trigger" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Your-Character-Id>",
         "trigger_message": "User has entered the museum.",
         "trigger_name": "StartTrigger",
         "destination_section": "<Destination-Section-ID-to-connect-to>"
     }'

Update Trigger

POST https://api.convai.com/character/narrative/update-trigger

Edit a Trigger. You would send all the fields that you want to update for a trigger via updated_data json. Following are the valid key.

  • "trigger_name": New trigger name. Must be unique.

  • "trigger_message": New trigger message.

  • "destination_section": New destination section-id for the trigger.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

character_id

String

Id of your character.

updated_data

Json

Contains fields that are updated.

trigger_id

String

Id of the trigger to update.

{
    "STATUS": "Successful",
    "message": "Trigger updated successfully"
}
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/narrative/update-trigger"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "character_id":"<Character-Id>",
    "trigger_id": "<Trigger-Id>",
    "updated_data": {
        "destination_section":"<New-Destination-Section-Id>",
        "trigger_message":"User has entered the Computer history museum"
    }   
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)                  
curl -X POST "https://api.convai.com/character/narrative/update-trigger" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Character-Id>",
         "trigger_id": "<Section-Id>",
         "updated_data": {
             "destination_section": "<New-Destination-Section-Id>",
             "trigger_message": "User has entered the Computer history museum"
         }
     }'

Delete Trigger

POST https://api.convai.com/character/narrative/delete-trigger

Delete an existing Trigger.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

character_id

String

Id of your character.

trigger_id

String

Id of the trigger to delete.

{
    "STATUS": "Successful",
    "message": "Trigger deleted successfully"
}
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/narrative/delete-trigger"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "character_id":"<Character-Id>",
    "trigger_id": "<Trigger-Id>",  
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)                 
curl -X POST "https://api.convai.com/character/narrative/delete-trigger" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
         "character_id": "<Character-Id>",
         "trigger_id": "<Trigger-Id>"
     }'

Get Trigger

POST https://api.convai.com/character/narrative/get-trigger

Fetch details of an existing Trigger.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

character_id

String

Id of your character.

trigger_id

String

Id of the trigger to fetch.

{
    "character_id": "<Character-Id>",
    "trigger_id": "<Trigger-Id>",
    "trigger_name": "UserEntry",
    "trigger_message": "User has entered the museum.",
    "destination_section": null,
    "node_position": []
}
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/narrative/get-trigger"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "character_id":"<Character-Id>",
    "trigger_id": "<Trigger-Id>",  
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)              
curl -X POST "https://api.convai.com/character/narrative/get-trigger" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
           "character_id": "<Character-Id>",
           "trigger_id": "<Trigger-Id>"
         }'

List Triggers

POST https://api.convai.com/character/narrative/list-triggers

List all the triggers for a Character.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

character_id

String

Id of your character.

[
  {
    "character_id": "<Character-Id>",
    "trigger_id": "<Trigger-ID1>",
    "trigger_name": "trigger 1",
    "trigger_message": "",
    "destination_section": null,
    "node_position": []
  },
  {
    "character_id": "<Character-Id>",
    "trigger_id": "<Trigger-ID2>",
    "trigger_name": "UserEntry",
    "trigger_message": "User has entered the museum.",
    "destination_section": null,
    "node_position": [ ]
  }
]
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/narrative/list-triggers"
headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "character_id":"<Character-Id>", 
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)              
curl -X POST "https://api.convai.com/character/narrative/list-triggers" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{"character_id":"<Character-Id>"}'
PreviousKnowledge Bank APINextAction API

Last updated 5 months ago

Was this helpful?