Narrative Design API

The page list all the APIs needed to interact Narrative Design

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/narrate/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/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}'

Edit Section

POST https://api.convai.com/character/narrate/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 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/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/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}'