Narrative Design API

The page list all the APIs needed to interact Narrative Design

API access requires an active Enterprise or Partner subscription.

Toggle Narrative Design

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

Enable/Disable 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.

200: OK

{"STATUS": "Successful"}

401 API Key validation has failed

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

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

Python

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

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.

200: OK Section Created

{
    "section_id": "<New-Section-Id>"
}

401 API Key validation has failed

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

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

Python

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

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.

200: OK Section Updated

{
    "status": "success",
    "section_id": "<Section-Id>",
    "updated_data": {
        "objective": "Some new objective."
    }
}

401 API Key validation has failed

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

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

Python

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

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.

200: OK Section Details

{
   "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": []
}

401 API Key validation has failed

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

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

Python

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

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.

200: OK List of Section Details

[
  {
    "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": []
  }
]

401 API Key validation has failed

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

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

Python

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

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.

200: OK Section Deleted

{"STATUS": "Successful"}

401 API Key validation has failed

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

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

Python

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

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.

200: OK Trigger Created

{
    "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": []
}

401 API Key validation has failed

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

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

Python

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

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.

200: OK Trigger Updated

{
    "STATUS": "Successful",
    "message": "Trigger updated successfully"
}

401 API Key validation has failed

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

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

Python

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

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.

200: OK Trigger Deleted

{
    "STATUS": "Successful",
    "message": "Trigger deleted successfully"
}

401 API Key validation has failed

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

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

Python

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

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.

200: OK Trigger Details

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

401 API Key validation has failed

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

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

Python

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

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.

200: OK List of Trigger Details

[
  {
    "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": [ ]
  }
]

401 API Key validation has failed

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

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

Python

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

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>"}'