> ## 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. # 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: ```json { "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: ```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" } ``` Text streaming is never disabled—`stream.delta` and the final `stream.end` payload always include the transcript even if voice playback is on. ## OpenAPI ````yaml /api-reference/openapi.yaml post /interactions openapi: 3.0.3 info: title: NPC Builder - API description: > This is the latest NPC Builder API specification that defines a comprehensive, production-ready API for NPC Builder. The API is divided into three primary services: **Interactions Service** - **Purpose:** Enables dynamic, context-aware conversations between players and NPC characters. **Context Service** - **Purpose:** Manages in-game entities to build and maintain immersive game environments. - **Includes:** - **Worlds:** Create, update, and delete game worlds. - **Regions:** Define and manage distinct regions within a world. - **Locations:** Handle specific locations within regions. - **Characters:** Manage the lifecycle (creation, updating, deletion) of NPC characters. **Sessions Service** - **Purpose:** Manages player sessions to maintain game context and track interactions. Overall, this specification serves as a detailed guide to leveraging NPC Builder’s services—empowering developers to build rich, interactive experiences while efficiently managing game contexts and entities. _You must stick to the data structure defined, otherwise you may encounter unhandled errors_ **Please check the schemas of each request to find the allowed values for certain properties.** _Technical Limitations: Character's knowledge and relationships updating and deleting are not available through the API. They must be managed through our app's frontend._ Some useful links: - [Our website](https://npcbuilder.com) - [The 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: Production API for context, sessions, and non-interaction endpoints security: [] tags: - name: Interactions description: Manage your NPCs text conversations and interactive responses. - name: Characters description: Manage characters in your game including creation, update, and deletion. - name: Worlds description: Create and manage immersive worlds for your game. - name: Regions description: Define and manage regions within your worlds. - name: Locations description: Manage specific locations within regions of your game. - name: Sessions description: Create, retrieve, and delete player sessions for enhanced game management. paths: /interactions: post: tags: - Interactions summary: Obtain a response from an NPC character description: > 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: ```json { "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: ```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" } ``` Text streaming is never disabled—`stream.delta` and the final `stream.end` payload always include the transcript even if voice playback is on. operationId: addInteraction parameters: - name: language in: query description: > The language code for the interaction. Supported values include: - **en-US**: English (United States) - **es-ES**: Spanish (Spain) required: true schema: type: string enum: - en-US - es-ES example: en-US - name: session_id in: query description: (Optional) The unique identifier for the player's session. required: false schema: type: string example: 60Z5aZjIuFlyYbjbZZKe - name: voice in: query description: > 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). required: false schema: type: string enum: - 'false' - 'true' - input - output default: 'false' requestBody: description: > 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. 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: > Successful operation. Returns the character's response along with any triggered user events. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' application/xml: schema: $ref: '#/components/schemas/ApiResponse' '206': description: > Partial content due to maximum length reached. The response may be truncated. content: application/json: schema: $ref: '#/components/schemas/MaxLength' application/xml: schema: $ref: '#/components/schemas/MaxLength' '401': description: Unauthorized – No valid token was provided. content: application/json: example: Unauthorized, no token provided '403': description: Forbidden – Invalid token provided. Try generating a new token. content: application/json: example: >- Unauthorized, invalid token provided. Try generating a new token. '409': description: > Conflict – Operation not allowed due to usage limits, non-existent objects, or unimplemented features. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorNoContext' - $ref: '#/components/schemas/ErrorUsageLimit' - $ref: '#/components/schemas/ErrorNotImplemented' '500': description: > Internal Server Error – An error occurred while processing the interaction. content: application/json: example: Error creating interaction security: - npcbuilder_auth: [] servers: - url: https://app.npcbuilder.com/api description: Production HTTP API for batch interactions - url: wss://api.app.npcbuilder.com/api description: Production WebSocket API for text streaming and voice interactions components: schemas: Interaction: type: object description: > 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. properties: character_id: type: string description: The unique identifier of the NPC character. example: a96c6161-59f5-40f7-955e-459cd11 game_id: type: string description: The unique identifier of the game. example: tx65BrETVN2vMrrUIrlV world_id: type: string description: The unique identifier of the world. example: PtUYW5bLMZNnXPN8qAUJ conversation_id: type: string description: >- (Optional) The unique identifier for the conversation history. If provided with empty messages, history will be loaded. example: conv_12345 messages: type: array description: An array of messages exchanged between the player and the NPC. xml: name: messages wrapped: true items: $ref: '#/components/schemas/Messages' user_context: type: object description: >- An object containing player-specific information for character context. properties: name: type: string description: The name of the player. example: Juan age: type: string description: The age of the player. example: Adult gender: type: string description: The gender of the player. example: Male race: type: string description: The race of the player. example: Human class: type: string description: The class of the player. example: Warrior level: type: integer description: The level of the player. example: 5 status: type: string description: The status of the player. example: Healthy description: type: string description: >- A brief description of the player used for characterizing it or its status. example: Smelly with a big sword and a wound in the chest xml: name: interaction ApiResponse: type: object description: > The ApiResponse schema represents the successful response from the API, including the NPC's response and any user-triggered events. properties: response: type: string description: The NPC's generated response. example: Hello Juan, my name is Jakinen user_events: type: array description: A list of events triggered by the user's input. items: type: object properties: name: type: string description: The name of the event. example: take item: type: string description: The item associated with the event, if any. nullable: true example: sword character_events: type: array description: A list of events triggered by the user's input. items: type: object properties: name: type: string description: The name of the event. example: take item: type: string description: The item associated with the event, if any. nullable: true example: sword example: 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 MaxLength: type: object description: > The MaxLength schema is used when the response has been truncated due to reaching the maximum allowed length. properties: response: type: string description: The truncated response from the NPC. example: Hello Juan, my name is Jakinen user_events: type: array description: A list of events triggered by the user's input. items: type: object properties: name: type: string description: The name of the event. example: take item: type: string description: The item associated with the event. nullable: true example: sword example: response: Hello Juan, my name is Jakinen user_events: - name: take item: sword - name: dance item: null ErrorNoContext: type: string description: | Error indicating that no world context has been defined. example: There is no world context defined. ErrorUsageLimit: type: string description: | Error indicating that the usage limit has been exceeded. example: >- Usage limit exceeded. Please check your subscription or interactions limit. ErrorNotImplemented: type: string description: | Error indicating that the requested operation is not implemented. example: Not implemented yet. Messages: type: object description: > A message object representing a single message in the conversation. The role indicates the sender ('user' for player messages, 'assistant' for NPC responses) and content holds the actual text. properties: role: type: string description: > The role of the message sender. Use 'user' for messages from the player and 'assistant' for NPC responses. enum: - user - assistant example: user content: type: string description: The text content of the message. example: Hello Jakinen, my name is Juan, I'll take my sword and dance! xml: name: messages_user securitySchemes: npcbuilder_auth: type: http scheme: bearer bearerFormat: JWT ````