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"
}
}
EOFimport requests
url = "https://app.npcbuilder.com/api/interactions"
payload = {
"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"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
}
})
};
fetch('https://app.npcbuilder.com/api/interactions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.npcbuilder.com/api/interactions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.npcbuilder.com/api/interactions"
payload := strings.NewReader("{\n \"character_id\": \"a96c6161-59f5-40f7-955e-459cd11\",\n \"game_id\": \"tx65BrETVN2vMrrUIrlV\",\n \"world_id\": \"PtUYW5bLMZNnXPN8qAUJ\",\n \"conversation_id\": \"conv_12345\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello Jakinen, my name is Juan, I'll take my sword and dance!\"\n }\n ],\n \"user_context\": {\n \"name\": \"Juan\",\n \"age\": \"Adult\",\n \"gender\": \"Male\",\n \"race\": \"Human\",\n \"class\": \"Warrior\",\n \"level\": 5,\n \"status\": \"Healthy\",\n \"description\": \"Smelly with a big sword and a wound in the chest\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.npcbuilder.com/api/interactions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"character_id\": \"a96c6161-59f5-40f7-955e-459cd11\",\n \"game_id\": \"tx65BrETVN2vMrrUIrlV\",\n \"world_id\": \"PtUYW5bLMZNnXPN8qAUJ\",\n \"conversation_id\": \"conv_12345\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello Jakinen, my name is Juan, I'll take my sword and dance!\"\n }\n ],\n \"user_context\": {\n \"name\": \"Juan\",\n \"age\": \"Adult\",\n \"gender\": \"Male\",\n \"race\": \"Human\",\n \"class\": \"Warrior\",\n \"level\": 5,\n \"status\": \"Healthy\",\n \"description\": \"Smelly with a big sword and a wound in the chest\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.npcbuilder.com/api/interactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"character_id\": \"a96c6161-59f5-40f7-955e-459cd11\",\n \"game_id\": \"tx65BrETVN2vMrrUIrlV\",\n \"world_id\": \"PtUYW5bLMZNnXPN8qAUJ\",\n \"conversation_id\": \"conv_12345\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello Jakinen, my name is Juan, I'll take my sword and dance!\"\n }\n ],\n \"user_context\": {\n \"name\": \"Juan\",\n \"age\": \"Adult\",\n \"gender\": \"Male\",\n \"race\": \"Human\",\n \"class\": \"Warrior\",\n \"level\": 5,\n \"status\": \"Healthy\",\n \"description\": \"Smelly with a big sword and a wound in the chest\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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
}
]
}{
"response": "Hello Juan, my name is Jakinen",
"user_events": [
{
"name": "take",
"item": "sword"
},
{
"name": "dance",
"item": null
}
]
}"Unauthorized, no token provided""Unauthorized, invalid token provided. Try generating a new token.""There is no world context defined.""Error creating interaction"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/interactionsrequest. The service buffers the model response and returns a single JSON payload that includesresponse,user_events, andcharacter_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.deltaevents – 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 plususer_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=truefor full duplex voice, or usevoice=input/voice=outputfor one-way voice. You can also providemeta.voiceinsideinteraction.start. - When voice is enabled the service mirrors the normalstream.*text flow and emits supplementalvoice.*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"
}
}
EOFimport requests
url = "https://app.npcbuilder.com/api/interactions"
payload = {
"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"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
}
})
};
fetch('https://app.npcbuilder.com/api/interactions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.npcbuilder.com/api/interactions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.npcbuilder.com/api/interactions"
payload := strings.NewReader("{\n \"character_id\": \"a96c6161-59f5-40f7-955e-459cd11\",\n \"game_id\": \"tx65BrETVN2vMrrUIrlV\",\n \"world_id\": \"PtUYW5bLMZNnXPN8qAUJ\",\n \"conversation_id\": \"conv_12345\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello Jakinen, my name is Juan, I'll take my sword and dance!\"\n }\n ],\n \"user_context\": {\n \"name\": \"Juan\",\n \"age\": \"Adult\",\n \"gender\": \"Male\",\n \"race\": \"Human\",\n \"class\": \"Warrior\",\n \"level\": 5,\n \"status\": \"Healthy\",\n \"description\": \"Smelly with a big sword and a wound in the chest\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.npcbuilder.com/api/interactions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"character_id\": \"a96c6161-59f5-40f7-955e-459cd11\",\n \"game_id\": \"tx65BrETVN2vMrrUIrlV\",\n \"world_id\": \"PtUYW5bLMZNnXPN8qAUJ\",\n \"conversation_id\": \"conv_12345\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello Jakinen, my name is Juan, I'll take my sword and dance!\"\n }\n ],\n \"user_context\": {\n \"name\": \"Juan\",\n \"age\": \"Adult\",\n \"gender\": \"Male\",\n \"race\": \"Human\",\n \"class\": \"Warrior\",\n \"level\": 5,\n \"status\": \"Healthy\",\n \"description\": \"Smelly with a big sword and a wound in the chest\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.npcbuilder.com/api/interactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"character_id\": \"a96c6161-59f5-40f7-955e-459cd11\",\n \"game_id\": \"tx65BrETVN2vMrrUIrlV\",\n \"world_id\": \"PtUYW5bLMZNnXPN8qAUJ\",\n \"conversation_id\": \"conv_12345\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello Jakinen, my name is Juan, I'll take my sword and dance!\"\n }\n ],\n \"user_context\": {\n \"name\": \"Juan\",\n \"age\": \"Adult\",\n \"gender\": \"Male\",\n \"race\": \"Human\",\n \"class\": \"Warrior\",\n \"level\": 5,\n \"status\": \"Healthy\",\n \"description\": \"Smelly with a big sword and a wound in the chest\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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
}
]
}{
"response": "Hello Juan, my name is Jakinen",
"user_events": [
{
"name": "take",
"item": "sword"
},
{
"name": "dance",
"item": null
}
]
}"Unauthorized, no token provided""Unauthorized, invalid token provided. Try generating a new token.""There is no world context defined.""Error creating interaction"Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
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"
(Optional) The unique identifier for the player's session.
Example:
"60Z5aZjIuFlyYbjbZZKe"
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
application/jsonapplication/xmlapplication/x-www-form-urlencoded
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.
The unique identifier of the NPC character.
Example:
"a96c6161-59f5-40f7-955e-459cd11"
The unique identifier of the game.
Example:
"tx65BrETVN2vMrrUIrlV"
The unique identifier of the world.
Example:
"PtUYW5bLMZNnXPN8qAUJ"
(Optional) The unique identifier for the conversation history. If provided with empty messages, history will be loaded.
Example:
"conv_12345"
An array of messages exchanged between the player and the NPC.
Show child attributes
Show child attributes
An object containing player-specific information for character context.
Show child attributes
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.