Reference

Sessions

Service to handle Inworld API sessions.

Method Name	Request Type	Response Type	Description
SimpleSendText	SimpleSendTextRequest	Interaction	RPC to send simple text request directly to single character.
OpenSession	OpenSessionRequest	Session	RPC to load world for the interaction session.
SendText	SendTextRequest	Interaction	RPC to send text to the previously opened session.
SendTrigger	SendTriggerRequest	Interaction	RPC to send trigger event to the previously opened session.

SimpleSendTextRequest

The request message for [Sessions.SimpleSendText][ai.inworld.engine.v1.Sessions.SimpleSendText].

characterrequired

string

Full resource name of the character to send text to. Format: workspaces/{workspace}/characters/{character}.

textrequired

string

Text to send to the character.

session_idoptional

string

Unique id of the session.

end_user_idoptional

string

Globally unique string, id of the end user of the system.

end_user_fullnameoptional

string

Full display name of the end user, this will be used by character in dialog.

Curl

curl -X POST https://api.inworld.ai/v1/workspaces/default-j_2vxrpapritcwrnvaiufq/characters/tony:simpleSendText \
-H 'Content-Type: application/json' \
-H 'authorization: Basic {YOUR_KEY_HERE}' \
-d '{"character":"workspaces/default-j_2vxrpapritcwrnvaiufq/characters/tony", "text":"hello there!", "endUserFullname":"John Adams", "endUserId":"1234"}'

Python

import requests

url = 'https://api.inworld.ai/v1/workspaces/default-j_2vxrpapritcwrnvaiufq/characters/tony:simpleSendText'
headers = {"Content-Type": "application/json", "authorization": "Basic {YOUR_KEY_HERE}"}
myobj = {"character":"workspaces/default-j_2vxrpapritcwrnvaiufq/characters/tony", "text":"hello there!", "endUserFullname":"John Adams", "endUserId":"1234"}

x = requests.post(url, json = myobj, headers=headers)

OpenSessionRequest

The request message for [Sessions.OpenSession][ai.inworld.engine.v1.Sessions.OpenSession].

namerequired

string

Scene or character resource name to be loaded by default. Format: workspaces/{workspace}/scenes/{scene} OR workspaces/{workspace}/characters/{character}.

useroptional

EndUserConfig

Configuration of the experience consumer. End User information.

Curl

curl -X POST https://api.inworld.ai/v1/workspaces/default-j_2vxrpapritcwrnvaiufq/characters/tony:openSession \
-H 'Content-Type: application/json' \
-H 'authorization: Basic {YOUR_KEY_HERE}' \
-d '{"name":"workspaces/default-j_2vxrpapritcwrnvaiufq/characters/tony"}'

Python

import requests

url = 'https://api.inworld.ai/v1/workspaces/default-j_2vxrpapritcwrnvaiufq/characters/tony:openSession'
headers = {"Content-Type": "application/json", "authorization": "Basic {YOUR_KEY_HERE}"}
myobj = {"name":"workspaces/default-j_2vxrpapritcwrnvaiufq/characters/tony"}

x = requests.post(url, json = myobj, headers=headers)

EndUserConfig

Configuration of the end user.

end_user_idoptional

string

Globally unique string, id of the end user of the system.

given_nameoptional

string

Full name of the user to be used by characters through the dialog.

genderoptional

string

Gender of user.

roleoptional

string

Role of user.

ageoptional

int64

Age of user.

{"user": {"endUserId": "12345", "givenName":"Sherlock", "gender": "female", "age":"27", "role": "detective"}}

SendTextRequest

The request message for [Sessions.SendText][ai.inworld.engine.v1.Sessions.SendText].

session_characterrequired

string

Full resource name of the addressed session character. Format: workspaces/{workspace}/sessions/{session}/sessionCharacters/{session_character}

textrequired

string

Text message to send to the character.

Curl

curl -X POST https://api.inworld.ai/v1/workspaces/default-j_2vxrpapritcwrnvaiufq/sessions/default-j_2vxrpapritcwrnvaiufq:06f80282-924d-4d39-8a03-0cd2b381015e/sessionCharacters/06963e0f-7320-4482-ac4a-e056eb82a160:sendText \
-H 'Content-Type: application/json' \
-H 'authorization: Basic {YOUR_KEY_HERE}' \
-H 'Grpc-Metadata-session-id: default-j_2vxrpapritcwrnvaiufq:06f80282-924d-4d39-8a03-0cd2b381015e' \
-d '{"text":"hello there"}'

Python

import requests

url = 'https://api.inworld.ai/v1/workspaces/default-j_2vxrpapritcwrnvaiufq/sessions/default-j_2vxrpapritcwrnvaiufq:06f80282-924d-4d39-8a03-0cd2b381015e/sessionCharacters/06963e0f-7320-4482-ac4a-e056eb82a160:sendText'
headers = {"Content-Type": "application/json", "authorization": "Basic {YOUR_KEY_HERE}", "Grpc-Metadata-session-id": "default-j_2vxrpapritcwrnvaiufq:06f80282-924d-4d39-8a03-0cd2b381015e"}
myobj = {"text":"hello there"}

x = requests.post(url, json = myobj, headers=headers)

SendTriggerRequest

The request message for [Sessions.SendTrigger][ai.inworld.engine.v1.Sessions.SendTrigger].

session_characterrequired

string

Full resource name of the addressed session character. Format: workspaces/{workspace}/sessions/{session}/sessionCharacters/{session_character}

trigger_eventrequired

TriggerEvent

custom event to send.

end_user_idoptional

string

Globally unique string, id of the end user of the system.

Curl

curl -X POST https://api.inworld.ai/v1/workspaces/default-j_2vxrpapritcwrnvaiufq/sessions/default-j_2vxrpapritcwrnvaiufq:06f80282-924d-4d39-8a03-0cd2b381015e/sessionCharacters/06963e0f-7320-4482-ac4a-e056eb82a160:sendTrigger \
-H 'Content-Type: application/json' \
-H 'authorization: Basic {YOUR_KEY_HERE}' \
-H 'Grpc-Metadata-session-id: default-j_2vxrpapritcwrnvaiufq:06f80282-924d-4d39-8a03-0cd2b381015e' \
-d '{"triggerEvent": { "trigger":"workspaces/default-j_2vxrpapritcwrnvaiufq/triggers/test" }}'

Python

import requests

url = 'https://api.inworld.ai/v1/workspaces/default-j_2vxrpapritcwrnvaiufq/sessions/default-j_2vxrpapritcwrnvaiufq:06f80282-924d-4d39-8a03-0cd2b381015e/sessionCharacters/06963e0f-7320-4482-ac4a-e056eb82a160:sendTrigger'
headers = {"Content-Type": "application/json", "authorization": "Basic {YOUR_KEY_HERE}", "Grpc-Metadata-session-id": "default-j_2vxrpapritcwrnvaiufq:06f80282-924d-4d39-8a03-0cd2b381015e"}
myobj = {"triggerEvent": { "trigger":"workspaces/default-j_2vxrpapritcwrnvaiufq/triggers/test" }}

x = requests.post(url, json = myobj, headers=headers)

TriggerEvent

Message describing trigger event structure.

triggerrequired

string

Name of the trigger event. Format: workspaces/{workspace}/triggers/{eventId}

parametersoptional

Parameter

Map of parameters to send along with the custom_event.

{"triggerEvent": { "trigger":"workspaces/{WORKSPACE_NAME_HERE}/triggers/test", "parameters":[{"name":"place", "value":"California"}] }}

Parameter

A list of parameters of TriggerEvent/CustomEvent. Only supports string values for now, but can be expanded in future on as-needed basis.

namerequired

string

Key name for parameter.

valuerequired

string

Key value for parameter.

"parameters":[{"name":"place", "value":"California"}]

Session

Response message for LoadScene RPC.

name string

Full resource name of the session. Format: workspaces/{workspace}/sessions/{session}

session_characters SessionCharacter

List of created agents

loaded_scene string

Full resource name of the default loaded scene. Format: workspaces/{workspace}/scenes/{scene} OR workspaces/{workspace}/characters/{character}.

Session.SessionCharacter

Message describing the runtime instance of the character

name string

Full resource name of the session character. Format: workspaces/{workspace}/sessions/{session}/sessionCharacters/{session_character}

character string

Full resource name of the referenced character. Format: workspaces/{workspace}/characters/{character}

display_name string

Character display name specified by developer.

character_assets CharacterAssets

Different assets for the character.

Session.SessionCharacter.CharacterAssets

Message that represents structured list of different assets associated with the character.

avatar_img string

Link to uploaded and resized avatar for character

avatar_img_original string

Link to uploaded original avatar for character

Interaction

The basic response message for a Simple Text request to a character.

name string

Full resource name of the interaction. Format: workspaces/{workspace}/sessions/{session}/interactions/{interaction}

text_list string

List of text responses. This list includes narrated actions in a form of something happened in correct order.

emotion Emotion

Describes emotion of the character on the moment of the end of interaction.

session_id string

session id that the interaction is in.

relationship_update RelationshipUpdate

Relationship updates.

active_triggers TriggerEvent

Active trigger.

Interaction.Emotion

Describes emotion of the session character.

behavior SpaffCode

Determines behavior affected by emotions.

strength Strength

Determines strength of the emotion.

Interaction.Emotion.SpaffCode

Describes character behavior affected by emotions. For more details of character emotions, check out Personality and Emotions.

Name	Number	Description
SPAFF_CODE_UNSPECIFIED	0	No emotion (mostly likely an error message)
NEUTRAL	1	Neutral.
DISGUST	2	Disgust.
CONTEMPT	3	Contempt.
BELLIGERENCE	4	Belligerence.
DOMINEERING	5	Domineering.
CRITICISM	6	Criticism.
ANGER	7	Anger.
TENSION	8	Tension.
TENSE_HUMOR	9	Tense humor.
DEFENSIVENESS	10	Defensiveness.
WHINING	11	Whining.
SADNESS	12	Sadness.
STONEWALLING	13	Stonewalling.
INTEREST	14	Interest.
VALIDATION	15	Validation.
AFFECTION	16	Affection.
HUMOR	17	Humor.
SURPRISE	18	Surprise.
JOY	19	Joy.

Interaction.Emotion.Strength

Describes strength of the emotion.

Name	Number	Description
STRENGTH_UNSPECIFIED	0	No strength (mostly likely an error message)
WEAK	1	Weak emotion.
STRONG	2	Strong emotion.
NORMAL	3	Normal emotion.

RelationshipUpdate

Relationship update object. Shows changes in relationship based on latest interaction.

trust int32

How much the character trusts the user.

respect int32

How much respect the character has for the user.

familiar int32

How familiar/comfortable the character is with the user.

flirtatious int32

How flirtatious the character is with the user.

attraction int32

How attracted the character is to the user.