Obtain a response from an NPC character

curl --request POST \
  --url https://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
    }
  ]
}

Interactions

Obtain a response from an NPC character

Send an array of interaction messages between the player and the NPC character. The API processes the conversation history and returns a new response generated by the character. Response modes

Batch HTTP (default): Perform a regular POST https://app.npcbuilder.com/api/interactions request. The service buffers the model response and returns a single JSON payload that includes response, user_events, and character_events.
Streaming WebSocket: Open a WebSocket connection to wss://api.app.npcbuilder.com/api/interactions. Once the socket is accepted, send a JSON envelope in the following format to start the interaction:
```
{
  "type": "interaction.start",
  "payload": { ...interaction body... },
  "meta": {
    "language": "en-US",
    "session_id": "optional-session"
  }
}
```
The server answers with:
- stream.accepted – confirms language / session and that generation started.
- Multiple stream.delta events – each contains the next safe sentence so that you can render audio/voice progressively.
- Optional stream.safe_response – emitted if a banned phrase is detected mid-stream (it also aborts the upstream model).
- stream.end – delivers the final transcript plus user_events, character_events, and usage totals.
You may cancel an ongoing generation by sending {"type":"interaction.cancel"}.

Voice live add-on (WebSocket only)

Connect to wss://api.app.npcbuilder.com/api/interactions?voice=true for full duplex voice, or use voice=input / voice=output for one-way voice. You can also provide meta.voice inside interaction.start. - When voice is enabled the service mirrors the normal stream.* text flow and emits supplemental voice.* events:
- voice.ready, voice.session.updated — Azure Voice Live session lifecycle.
- voice.audio.delta, voice.audio.timestamp, voice.audio.done, voice.response.done — assistant text-to-speech audio.
- voice.transcript.delta, voice.input.started/stopped, voice.usage — microphone audio that was ingested through speech-to-text.

Client commands accepted during an active session:

{ "type": "voice.input.append", "data": { "audio": "<base64 pcm16 chunk>" } }
{ "type": "voice.input.commit" }
{ "type": "voice.input.clear" }
{ "type": "voice.session.update", "data": { "voice_name": "en-US-Ava:DragonHDLatestNeural" } }
{ "type": "voice.cancel" }

Text streaming is never disabled—stream.delta and the final stream.end payload always include the transcript even if voice playback is on.

POST

interactions

Obtain a response from an NPC character

curl --request POST \
  --url https://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.

Show child attributes

user_context

object

An object containing player-specific information for character context.

Show child attributes

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.

Show child attributes

character_events

object[]

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

Show child attributes

Authentication List conversations