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
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
character_id
String
Id of your character.
is_narrative_driven
Bool
Set it to true or false, to enable disable Narrative Graph.
{"STATUS": "Successful"}
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)
Create Section
POST
https://api.convai.com/character/narrative/create-section
Create new section for your Character.
Headers
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
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>"
}
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)
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
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
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."
}
}
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)
Get Section
POST
https://api.convai.com/character/narrative/get-section
Get details for a particular narrative section of your Character.
Headers
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
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": []
}
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)
List Sections
POST
https://api.convai.com/character/narrative/list-sections
List details of all narrative sections for a given character.
Headers
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
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": []
}
]
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)
Delete Section
POST
https://api.convai.com/character/narrative/delete-section
Delete a narrative section of your Character.
Headers
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
character_id
String
Id of your character.
section_id
String
Id of the section to delete.
{"STATUS": "Successful"}
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)
Create Trigger
POST
https://api.convai.com/character/narrative/create-trigger
Create a new Trigger for your Character.
Headers
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
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": []
}
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)
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
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
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"
}
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)
Delete Trigger
POST
https://api.convai.com/character/narrative/delete-trigger
Delete an existing Trigger.
Headers
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
character_id
String
Id of your character.
trigger_id
String
Id of the trigger to delete.
{
"STATUS": "Successful",
"message": "Trigger deleted successfully"
}
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)
Get Trigger
POST
https://api.convai.com/character/narrative/get-trigger
Fetch details of an existing Trigger.
Headers
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
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": []
}
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)
List Triggers
POST
https://api.convai.com/character/narrative/list-triggers
List all the triggers for a Character.
Headers
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
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": [ ]
}
]
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)
Last updated
Was this helpful?