Skip to main content

Reference

Sessions

Service to handle Inworld API sessions.

Method NameRequest TypeResponse TypeDescription
SimpleSendTextSimpleSendTextRequestInteractionRPC to send simple text request directly to single character.
OpenSessionOpenSessionRequestSessionRPC to load world for the interaction session.
SendTextSendTextRequestInteractionRPC to send text to the previously opened session.
SendTriggerSendTriggerRequestInteractionRPC 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 -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"}'

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

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

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

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.

NameNumberDescription
SPAFF_CODE_UNSPECIFIED0No emotion (mostly likely an error message)
NEUTRAL1Neutral.
DISGUST2Disgust.
CONTEMPT3Contempt.
BELLIGERENCE4Belligerence.
DOMINEERING5Domineering.
CRITICISM6Criticism.
ANGER7Anger.
TENSION8Tension.
TENSE_HUMOR9Tense humor.
DEFENSIVENESS10Defensiveness.
WHINING11Whining.
SADNESS12Sadness.
STONEWALLING13Stonewalling.
INTEREST14Interest.
VALIDATION15Validation.
AFFECTION16Affection.
HUMOR17Humor.
SURPRISE18Surprise.
JOY19Joy.

Interaction.Emotion.Strength

Describes strength of the emotion.

NameNumberDescription
STRENGTH_UNSPECIFIED0No strength (mostly likely an error message)
WEAK1Weak emotion.
STRONG2Strong emotion.
NORMAL3Normal 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.