Skip to main content
POST
/
interactions
Obtain a response from an NPC character
curl --request POST \
  --url https://api.app.npcbuilder.com/api/interactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "character_id": "a96c6161-59f5-40f7-955e-459cd11",
  "game_id": "tx65BrETVN2vMrrUIrlV",
  "world_id": "PtUYW5bLMZNnXPN8qAUJ",
  "conversation_id": "conv_12345",
  "messages": [
    {
      "role": "user",
      "content": "Hello Jakinen, my name is Juan, I'll take my sword and dance!"
    }
  ],
  "user_context": {
    "name": "Juan",
    "age": "Adult",
    "gender": "Male",
    "race": "Human",
    "class": "Warrior",
    "level": 5,
    "status": "Healthy",
    "description": "Smelly with a big sword and a wound in the chest"
  }
}
EOF
{
  "response": "Hello Juan, my name is Jakinen",
  "user_events": [
    {
      "name": "take",
      "item": "sword"
    },
    {
      "name": "dance",
      "item": null
    }
  ],
  "character_events": [
    {
      "name": "give",
      "item": "shield"
    },
    {
      "name": "attack",
      "item": null
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
language
enum<string>
required

The language code for the interaction. Supported values include: - en-US: English (United States) - es-ES: Spanish (Spain)

Available options:
en-US,
es-ES
Example:

"en-US"

​
session_id
string

(Optional) The unique identifier for the player's session.

Example:

"60Z5aZjIuFlyYbjbZZKe"

​
voice
enum<string>
default:false

Optional. Controls Azure Voice Live streaming when using WebSockets. Allowed values:

  • false (default): disable voice, text only. * true: enable full duplex (speech-to-text + text-to-speech). * input: only capture microphone input (speech-to-text). * output: only synthesize assistant audio (text-to-speech).
Available options:
false,
true,
input,
output

Body

A JSON, XML, or URL-encoded payload containing the complete conversation history. Ensure messages are sent as an array of objects following the defined schema.

The Interaction schema defines the structure for a conversation between a player and an NPC. It includes metadata such as character ID, game ID, world ID, and an array of messages.

​
character_id
string

The unique identifier of the NPC character.

Example:

"a96c6161-59f5-40f7-955e-459cd11"

​
game_id
string

The unique identifier of the game.

Example:

"tx65BrETVN2vMrrUIrlV"

​
world_id
string

The unique identifier of the world.

Example:

"PtUYW5bLMZNnXPN8qAUJ"

​
conversation_id
string

(Optional) The unique identifier for the conversation history. If provided with empty messages, history will be loaded.

Example:

"conv_12345"

​
messages
object[]

An array of messages exchanged between the player and the NPC.

​
user_context
object

An object containing player-specific information for character context.

Response

Successful operation. Returns the character's response along with any triggered user events.

The ApiResponse schema represents the successful response from the API, including the NPC's response and any user-triggered events.

​
response
string

The NPC's generated response.

Example:

"Hello Juan, my name is Jakinen"

​
user_events
object[]

A list of events triggered by the user's input.

​
character_events
object[]

A list of events triggered by the user's input.