Skip to main content

Getting Started

Welcome to Inworld API! In this guide, we'll walk you through the steps to get started with integrating our AI characters into your applications. Let's dive in ➡️

Endpoints​

Root endpoint for all requests: https://api.inworld.ai/.

Header values​

NameRequired forDescriptionSample value (not real ones)
authorizationevery request.“Basic “ + authorization signatureBasic ZXhh8TBsZT9rZXlfcheyaW5nOmV4Y1234GVfc2VjcmV0X3N0cmuuZw==
Grpc-Metadata-session-idall session managed API requestsConcatenation of the workspace name and the UUID returned in OpenSession.default-ws:df2a986e-2023-0711-sher-88abcde1354e

Authorization signature​

info

Please note that API Keys and the generated authorization signature are unique per account and workspace. This means that an API Key generated in workspace-1 will not work to authorize API requests to a character in workspace-2.

To authorize your requests, you'll need a base64 authorization signature associated with your Inworld account.

Follow these steps to retrieve them:

  1. Log into Inworld Studio.
  2. Go to the Integrations tab
  3. Under API Keys, generate a new key pair.
  4. Click the "Copy Base64" button next to your API key to copy the authorization signature to your clipboard.

You will be using this key in the authorization header of all requests.

Integrations

base64

security

Please note that it is VERY important that you keep both of API key and secret confidential. Anyone who has access to the key/secret pair will be able to make requests to your account and characters. If you suspect a compromise, deactivate the key/secret pair immediately from the Studio console and generate a new one.

Make your first requests​

Now that you have your API key and secret ready, it's time to make your first requests to interact with the AI characters. We offer two integration options: Simple Integration and Fully Managed Integration. Each approach has its own benefits and considerations. Here's a guide to help you choose the right approach for your needs:

looking for simplicity?

Simple Integration is recommended if:

  • You want a quick and easy way to get started.
  • Conversation history and persistence are not crucial for your application.

or

need fine-grained control over sessions?

Fully Managed Integration is recommended if:

  • You have specific requirements for session management and conversation history.
  • You want complete control over the session flow and need to maintain session history across multiple requests.
  • You need to send trigger events or goals to your character.

Note All session expire after 30 mins of inactivity. Conversation history will NOT persist to a new session.

Simple Integration​

With the Simple Integration, you can use the SimpleSendText API to send quick conversation requests to your character. You don't need to worry about opening and managing sessions. The system will handle it for you.

Request Type: GET/POST

Request URL:

https://api.inworld.ai/v1/{character}:simpleSendText

Be sure to include the authorization header in your requests.

Parameters​

NameDescriptionExample value
characterResource name for the character you are speaking to. This is the same regardless of session instance and is targeting the base character.workspaces/{WORKSPACE_ID}/characters/tony
sessionId(OPTIONAL) Field returned in Interaction object. Leave blank if you would like to begin a new session.default-ws:df2a986e-2023-0711-sher-88abcde1354e
textThe actual text you would like to send to your character."Hello there!"
endUserFullnameDisplay name of the end user, this will be used by characters in dialog."Tom"
endUserIdUnique id of end user12345

Sample Request​

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

When making your first request, leave the sessionId blank to initiate a new character session. Your Interaction response will include a sessionId. Use this value in future requests to continue the conversation with the existing session agent.

Note: If the sessionId does not exist or refers to an expired session (30-minute timeout), a new session will be provisioned for you to seamlessly speak to the character. However, conversation history will not persist to this new session. You may face unexpected behavior with the conversation history with a new sessionId. If you would like greater control over this, please follow the steps in the Fully Managed Integration.

Fully Managed Integration​

With the Fully Managed Integration, you have granular control over the entire session flow. You can use the OpenSession, SendText, and SendTrigger APIs to manage sessions, send text messages, and trigger events to your character. This approach allows you to create more sophisticated interactions and maintain session state.

Make an API request to open a new session.​

We need to first start by opening a new session with a character. The OpenSession API will help us take care of this operation.

Request Type: POST

Request URL:

https://api.inworld.ai/v1/{name}:openSession

Be sure to include the authorization header in your requests.

Parameters​

NameDescriptionExample value
nameThis is the full resourceId of your character including workspaceId and character nameworkspaces/{WORKSPACE_ID}/characters/tony
userThis is a JSON object used to define end user configurations.{"endUserId": "12345", "givenName":"Sherlock", "gender": "female", "age":"27", "role": "detective"}

Sample Request​

curl -X POST https://api.inworld.ai/v1/workspaces/{WORKSPACE_ID}/characters/tony:openSession \
-H 'Content-Type: application/json' \
-H 'authorization: Basic {YOUR_KEY_HERE}' \
-d '{"name":"workspaces/{WORKSPACE_ID}/characters/tony", "user": {"endUserId": "12345", "givenName":"Sherlock", "gender": "female", "age":"27", "role": "detective"}}'

Sample Response​

{
  "name": "{SESSION_ID}",
  "sessionCharacters": [
    {
      "name": "workspaces/{WORKSPACE_ID}/characters/tony",
      "character": "{CHARACTER_ID}",
      "displayName": "Tony",
      "characterAssets": {
        "avatarImg": "",
        "avatarImgOriginal": ""
      }
    }
  ],
  "loadedScene": ""
}

Lets breakdown what we have received in the Session response.

NameDescription
Session.nameThis is the id of the session, which is a combination of your workspaceId and the UUID of the specific session. You will use this to reference the session when sending text messages to your character.
Session.sessionCharactersThis is a list of all of the loaded characters in a given session. For now it will just be one, but stay tuned for the ability to speak to a full scene later!
Session.sessionCharacters.nameThis is the resourceId identifying the character. Same as what you used in the main request`
Session.sessionCharacters.characterThis is the agentId of the specific character instance that is being used in your session. Please use this in your future simple text message requests
Session.sessionCharacters.displayNameThis is the display name of your character
Session.sessionCharacters.characterAssetsThese are reference assets for your character image

Send a text message to your character.​

Now that we have loaded the character and established a new session, it is time to talk with our character! The SendText API will let us send a text message to our character.

Request Type: POST

Request URL:

https://api.inworld.ai/v1/workspaces/{workspace_id}/sessions/{session_id}/sessionCharacters/{character_id}:sendText

Be sure to include the authorization and Grpc-Metadata-session-id header in your requests.

NOTE: The character_id here is what was returned from OpenSession object

Request Body:

{
    "text": "your text message
}

Sample Request​

curl -X POST https://api.inworld.ai/v1/workspaces/{WORKSPACE_ID}/sessions/{SESSION_ID}/sessionCharacters/06963e0f-7320-4482-ac4a-e056eb82a160:sendText \
-H 'Content-Type: application/json' \
-H 'authorization: Basic {YOUR_KEY_HERE}' \
-H 'Grpc-Metadata-session-id: {SESSION_ID}' \
-d '{"text":"hello there"}'

Send a trigger event (goal) to your character.​

We can send triggers events and goals to your character so they can react accordingly to custom triggered events.

First, go to the Studio and create a custom Goal (under the Goals tab in your character Studio). For detailed guide on Inworld Goals system, check out Goals doc.

Then, make sure that you have a valid OpenSession. The SendTrigger Request API will let us send a trigger event to our character that invokes the event trigger.

Request Type: POST

Request URL:

https://api.inworld.ai/v1/workspaces/{workspace_id}/sessions/{session_id}/sessionCharacters/{character_id}:sendTrigger

Be sure to include the authorization and Grpc-Metadata-session-id header in your requests.

NOTE: The character_id here is what was returned from OpenSession object (similar to what you use in sendText)

Request Body:

{
    "triggerEvent": {
        "trigger": "workspaces/{workspace_id}/triggers/{trigger_id}"
    }
}

Sample Request​

curl -X POST https://api.inworld.ai/v1/workspaces/{WORKSPACE_ID}/sessions/{SESSION_ID}/sessionCharacters/{CHARACTER_ID}:sendTrigger \
-H 'Content-Type: application/json' \
-H 'authorization: Basic {YOUR_KEY_HERE}' \
-H 'Grpc-Metadata-session-id: {SESSION_ID}' \
-d '{"triggerEvent": { "trigger":"workspaces/{WORKSPACE_ID}/triggers/test" }}'

That's it🎉 You're now equipped with the knowledge to integrate with Inworld API. Have fun conversing with your characters and exploring the possibilities!