> ## Documentation Index > Fetch the complete documentation index at: https://docs.npcbuilder.com/llms.txt > Use this file to discover all available pages before exploring further. # 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: ```json { "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: ```json { "type": "voice.input.append", "data": { "audio": "" } } { "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. ## OpenAPI ````yaml /es/api-reference/openapi.yaml post /interactions openapi: 3.0.3 info: title: NPC Builder - API description: > Esta es la especificación más reciente de la API de NPC Builder que define una API integral y lista para producción para NPC Builder. La API se divide en tres servicios principales: **Servicio de Interacciones** - **Propósito:** Permite conversaciones dinámicas y con conciencia de contexto entre jugadores y personajes NPC. **Servicio de Contexto** - **Propósito:** Gestiona entidades del juego para construir y mantener entornos inmersivos. - **Incluye:** - **Mundos:** Crear, actualizar y eliminar mundos del juego. - **Regiones:** Definir y gestionar regiones dentro de un mundo. - **Localizaciones:** Gestionar ubicaciones específicas dentro de las regiones. - **Personajes:** Gestionar el ciclo de vida (creación, actualización, eliminación) de personajes NPC. **Servicio de Sesiones** - **Propósito:** Gestiona sesiones de jugadores para mantener el contexto del juego y rastrear interacciones. En conjunto, esta especificación sirve como una guía detallada para aprovechar los servicios de NPC Builder—permitiendo a los desarrolladores crear experiencias ricas e interactivas mientras gestionan de forma eficiente contextos y entidades del juego. _Debes ceñirte a la estructura de datos definida; de lo contrario puedes encontrar errores no controlados_ **Consulta los esquemas de cada solicitud para encontrar los valores permitidos de ciertas propiedades.** _Limitaciones técnicas: La actualización y eliminación del conocimiento y las relaciones de los personajes no están disponibles a través de la API. Deben gestionarse desde el frontend de nuestra aplicación._ Algunos enlaces útiles: - [Nuestro sitio web](https://npcbuilder.com) - [La app](https://app.npcbuilder.com) termsOfService: https://npcbuilder.com/terms-and-conditions/ contact: email: support@npcbuilder.com version: 1.6.0 servers: - url: https://app.npcbuilder.com/api description: >- API de producción para contexto, sesiones y endpoints que no son de interacciones security: [] tags: - name: Interactions description: >- Gestiona las conversaciones de texto de tus NPCs y sus respuestas interactivas. - name: Characters description: >- Gestiona personajes de tu juego, incluyendo creación, actualización y eliminación. - name: Worlds description: Crea y gestiona mundos inmersivos para tu juego. - name: Regions description: Define y gestiona regiones dentro de tus mundos. - name: Locations description: Gestiona ubicaciones específicas dentro de las regiones de tu juego. - name: Sessions description: >- Crea, recupera y elimina sesiones de jugadores para una mejor gestión del juego. paths: /interactions: post: tags: - Interactions summary: Obtener una respuesta de un personaje NPC description: > 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: ```json { "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: ```json { "type": "voice.input.append", "data": { "audio": "" } } { "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. operationId: addInteraction parameters: - name: language in: query description: > El código de idioma para la interacción. Valores admitidos: - **en-US**: Inglés (Estados Unidos) - **es-ES**: Español (España) required: true schema: type: string enum: - en-US - es-ES example: en-US - name: session_id in: query description: (Opcional) El identificador único de la sesión del jugador. required: false schema: type: string example: 60Z5aZjIuFlyYbjbZZKe - name: voice in: query description: > 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). required: false schema: type: string enum: - 'false' - 'true' - input - output default: 'false' requestBody: description: > 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. content: application/json: schema: $ref: '#/components/schemas/Interaction' application/xml: schema: $ref: '#/components/schemas/Interaction' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Interaction' required: true responses: '200': description: > Operación exitosa. Devuelve la respuesta del personaje junto con cualquier evento de usuario desencadenado. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' application/xml: schema: $ref: '#/components/schemas/ApiResponse' '206': description: > Contenido parcial por alcanzar la longitud máxima. La respuesta puede estar truncada. content: application/json: schema: $ref: '#/components/schemas/MaxLength' application/xml: schema: $ref: '#/components/schemas/MaxLength' '401': description: No autorizado – No se proporcionó un token válido. content: application/json: example: No autorizado, no se proporcionó token '403': description: >- Prohibido – Se proporcionó un token inválido. Intenta generar un token nuevo. content: application/json: example: No autorizado, token inválido. Intenta generar un token nuevo. '409': description: > Conflicto – Operación no permitida debido a límites de uso, objetos inexistentes o funciones no implementadas. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorNoContext' - $ref: '#/components/schemas/ErrorUsageLimit' - $ref: '#/components/schemas/ErrorNotImplemented' '500': description: > Error interno del servidor – Ocurrió un error al procesar la interacción. content: application/json: example: Error al crear la interacción security: - npcbuilder_auth: [] servers: - url: https://app.npcbuilder.com/api description: API HTTP de producción para interacciones batch - url: wss://api.app.npcbuilder.com/api description: >- API WebSocket de producción para interacciones con streaming de texto y voz components: schemas: Interaction: type: object description: > 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. properties: conversation_id: type: string description: >- (Opcional) El identificador único de la conversación existente para cargar/persistir el historial. example: conv_12345 character_id: type: string description: El identificador único del personaje NPC. example: a96c6161-59f5-40f7-955e-459cd11 game_id: type: string description: El identificador único del juego. example: tx65BrETVN2vMrrUIrlV world_id: type: string description: El identificador único del mundo. example: PtUYW5bLMZNnXPN8qAUJ messages: type: array description: Un array de mensajes intercambiados entre el jugador y el NPC. xml: name: messages wrapped: true items: $ref: '#/components/schemas/Messages' user_context: type: object description: >- Un objeto que contiene información específica del jugador para el contexto del personaje. properties: name: type: string description: El nombre del jugador. example: Juan age: type: string description: La edad del jugador. example: Adult gender: type: string description: El género del jugador. example: Male race: type: string description: La raza del jugador. example: Human class: type: string description: La clase del jugador. example: Warrior level: type: integer description: El nivel del jugador. example: 5 status: type: string description: El estado del jugador. example: Healthy description: type: string description: >- Breve descripción del jugador usada para caracterizarlo o describir su estado. example: Huele mal, con una gran espada y una herida en el pecho xml: name: interaction ApiResponse: type: object description: > El esquema ApiResponse representa la respuesta correcta de la API, incluyendo la respuesta del NPC y cualquier evento desencadenado por el usuario. properties: response: type: string description: La respuesta generada por el NPC. example: Hola Juan, me llamo Jakinen user_events: type: array description: Una lista de eventos desencadenados por la entrada del usuario. items: type: object properties: name: type: string description: El nombre del evento. example: take item: type: string description: El objeto asociado al evento, si lo hay. nullable: true example: sword character_events: type: array description: Una lista de eventos desencadenados por la entrada del usuario. items: type: object properties: name: type: string description: El nombre del evento. example: take item: type: string description: El objeto asociado al evento, si lo hay. nullable: true example: sword example: 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 MaxLength: type: object description: > El esquema MaxLength se utiliza cuando la respuesta ha sido truncada por alcanzar la longitud máxima permitida. properties: response: type: string description: La respuesta truncada del NPC. example: Hola Juan, me llamo Jakinen user_events: type: array description: Una lista de eventos desencadenados por la entrada del usuario. items: type: object properties: name: type: string description: El nombre del evento. example: take item: type: string description: El objeto asociado al evento. nullable: true example: sword example: response: Hola Juan, me llamo Jakinen user_events: - name: take item: sword - name: dance item: null ErrorNoContext: type: string description: | Error que indica que no se ha definido un contexto de mundo. example: No hay un contexto de mundo definido. ErrorUsageLimit: type: string description: | Error que indica que se ha excedido el límite de uso. example: >- Límite de uso excedido. Revisa tu suscripción o el límite de interacciones. ErrorNotImplemented: type: string description: | Error que indica que la operación solicitada no está implementada. example: Aún no implementado. Messages: type: object description: > Un objeto de mensaje que representa un único mensaje en la conversación. El rol indica el remitente ('user' para mensajes del jugador, 'assistant' para respuestas del NPC) y 'content' contiene el texto. properties: role: type: string description: > El rol del remitente del mensaje. Usa 'user' para mensajes del jugador y 'assistant' para respuestas del NPC. enum: - user - assistant example: user content: type: string description: El contenido de texto del mensaje. example: Hola Jakinen, me llamo Juan, ¡cogeré mi espada y bailaré! xml: name: messages_user securitySchemes: npcbuilder_auth: type: http scheme: bearer bearerFormat: JWT ````