Obtener una respuesta de un personaje NPC

curl --request POST \
  --url https://app.npcbuilder.com/api/interactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversation_id": "conv_12345",
  "character_id": "a96c6161-59f5-40f7-955e-459cd11",
  "game_id": "tx65BrETVN2vMrrUIrlV",
  "world_id": "PtUYW5bLMZNnXPN8qAUJ",
  "messages": [
    {
      "role": "user",
      "content": "Hola Jakinen, me llamo Juan, ¡cogeré mi espada y bailaré!"
    }
  ],
  "user_context": {
    "name": "Juan",
    "age": "Adult",
    "gender": "Male",
    "race": "Human",
    "class": "Warrior",
    "level": 5,
    "status": "Healthy",
    "description": "Huele mal, con una gran espada y una herida en el pecho"
  }
}
'

{
  "response": "Hola Juan, me llamo Jakinen",
  "user_events": [
    {
      "name": "take",
      "item": "sword"
    },
    {
      "name": "dance",
      "item": null
    }
  ],
  "character_events": [
    {
      "name": "give",
      "item": "shield"
    },
    {
      "name": "attack",
      "item": null
    }
  ]
}

Interactions

Obtener una respuesta de un personaje NPC

Envía un array de mensajes de interacción entre el jugador y el personaje NPC. La API procesa el historial de conversación y devuelve una nueva respuesta generada por el personaje. Modos de respuesta

HTTP batch (por defecto): Envía una petición POST https://app.npcbuilder.com/api/interactions. El servicio compone toda la respuesta y entrega un JSON con response, user_events y character_events.
Streaming por WebSocket: Abre una conexión WebSocket a wss://api.app.npcbuilder.com/api/interactions. Una vez aceptada, envía:
```
{
  "type": "interaction.start",
  "payload": { ...interacción... },
  "meta": {
    "language": "es-ES",
    "session_id": "opcional"
  }
}
```
El servidor emite los eventos stream.accepted, varios stream.delta, opcionalmente stream.safe_response cuando se detecta una frase vetada y, al finalizar, stream.end con el texto completo, los eventos y los tokens consumidos.

Envía {"type":"interaction.cancel"} para abortar una generación.

Complemento de voz (solo WebSocket)

Conecta a wss://api.app.npcbuilder.com/api/interactions?voice=true para voz bidireccional, o usa voice=input / voice=output para voz en un solo sentido. También puedes proporcionar meta.voice dentro de interaction.start. - Con voz habilitada se mantienen los eventos stream.* de texto y además se envían eventos voice.*:
- voice.ready, voice.session.updated — estado de la sesión de Azure Voice Live.
- voice.audio.delta, voice.audio.timestamp, voice.audio.done, voice.response.done — audio generado por el asistente.
- voice.transcript.delta, voice.input.started/stopped, voice.usage — audio del micrófono transcrito por el servicio.

Comandos aceptados mientras la sesión está activa:

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

El streaming de texto nunca se desactiva: siempre recibirás stream.delta y el stream.end final, incluso cuando la reproducción de voz está activa.

POST

interactions

Obtener una respuesta de un personaje NPC

curl --request POST \
  --url https://app.npcbuilder.com/api/interactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversation_id": "conv_12345",
  "character_id": "a96c6161-59f5-40f7-955e-459cd11",
  "game_id": "tx65BrETVN2vMrrUIrlV",
  "world_id": "PtUYW5bLMZNnXPN8qAUJ",
  "messages": [
    {
      "role": "user",
      "content": "Hola Jakinen, me llamo Juan, ¡cogeré mi espada y bailaré!"
    }
  ],
  "user_context": {
    "name": "Juan",
    "age": "Adult",
    "gender": "Male",
    "race": "Human",
    "class": "Warrior",
    "level": 5,
    "status": "Healthy",
    "description": "Huele mal, con una gran espada y una herida en el pecho"
  }
}
'

{
  "response": "Hola Juan, me llamo Jakinen",
  "user_events": [
    {
      "name": "take",
      "item": "sword"
    },
    {
      "name": "dance",
      "item": null
    }
  ],
  "character_events": [
    {
      "name": "give",
      "item": "shield"
    },
    {
      "name": "attack",
      "item": null
    }
  ]
}

Autorizaciones

Authorization

string

header

requerido

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

Parámetros de consulta

language

enum<string>

requerido

El código de idioma para la interacción. Valores admitidos: - en-US: Inglés (Estados Unidos) - es-ES: Español (España)

Opciones disponibles:

en-US,

es-ES

Ejemplo:

"en-US"

session_id

string

(Opcional) El identificador único de la sesión del jugador.

Ejemplo:

"60Z5aZjIuFlyYbjbZZKe"

voice

enum<string>

predeterminado:false

Opcional. Controla el complemento de Azure Voice Live cuando se usa WebSocket. Valores aceptados:

false (predeterminado): desactiva la voz. * true: habilita audio bidireccional (STT + TTS). * input: solo captura voz del usuario (STT). * output: solo sintetiza el audio del asistente (TTS).

Opciones disponibles:

false,

true,

input,

output

Cuerpo

Una carga útil en JSON, XML o codificada en URL que contiene el historial completo de la conversación. Asegúrate de enviar los mensajes como un array de objetos siguiendo el esquema definido.

El esquema Interaction define la estructura para una conversación entre un jugador y un NPC. Incluye metadatos como ID del personaje, ID del juego, ID del mundo y un array de mensajes.

conversation_id

string

(Opcional) El identificador único de la conversación existente para cargar/persistir el historial.

Ejemplo:

"conv_12345"

character_id

string

El identificador único del personaje NPC.

Ejemplo:

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

game_id

string

El identificador único del juego.

Ejemplo:

"tx65BrETVN2vMrrUIrlV"

world_id

string

El identificador único del mundo.

Ejemplo:

"PtUYW5bLMZNnXPN8qAUJ"

messages

object[]

Un array de mensajes intercambiados entre el jugador y el NPC.

Show child attributes

user_context

object

Un objeto que contiene información específica del jugador para el contexto del personaje.

Show child attributes

Respuesta

Operación exitosa. Devuelve la respuesta del personaje junto con cualquier evento de usuario desencadenado.

El esquema ApiResponse representa la respuesta correcta de la API, incluyendo la respuesta del NPC y cualquier evento desencadenado por el usuario.

response

string

La respuesta generada por el NPC.

Ejemplo:

"Hola Juan, me llamo Jakinen"

user_events

object[]

Una lista de eventos desencadenados por la entrada del usuario.

Show child attributes

character_events

object[]

Una lista de eventos desencadenados por la entrada del usuario.

Show child attributes

Authentication Listar conversaciones

Documentation Index

Autorizaciones

Parámetros de consulta

Cuerpo

Respuesta