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].
string
Full resource name of the character to send text to. Format: workspaces/{workspace}/characters/{character}.
string
Text to send to the character.
string
Unique id of the session.
string
Globally unique string, id of the end user of the system.
string
Full display name of the end user, this will be used by character in dialog.
- Curl
- Python
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"}'
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].
string
Scene or character resource name to be loaded by default. Format: workspaces/{workspace}/scenes/{scene} OR workspaces/{workspace}/characters/{character}.
Configuration of the experience consumer. End User information.
- Curl
- Python
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"}'
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.
string
Globally unique string, id of the end user of the system.
string
Full name of the user to be used by characters through the dialog.
string
Gender of user.
string
Role of user.
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].
string
Full resource name of the addressed session character. Format: workspaces/{workspace}/sessions/{session}/sessionCharacters/{session_character}
string
Text message to send to the character.
- Curl
- Python
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"}'
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].
string
Full resource name of the addressed session character. Format: workspaces/{workspace}/sessions/{session}/sessionCharacters/{session_character}
custom event to send.
string
Globally unique string, id of the end user of the system.
- Curl
- Python
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" }}'
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.
string
Name of the trigger event. Format: workspaces/{workspace}/triggers/{eventId}
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.
string
Key name for parameter.
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.