> For the complete documentation index, see [llms.txt](https://docs.nlx.ai/platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nlx.ai/platform/developers/conversation-api/websocket/async-api-spec.md). # Async API spec ```yaml asyncapi: 2.6.0 info: title: NLX WebSocket API version: 1.0.0 description: > Real-time WebSocket interface for NLX apps allowing persistent connections for low-latency conversations. servers: production: url: wss://us-east-1-ws.apps.nlx.ai protocol: wss description: WebSocket Endpoint channels: /: description: > The main conversation channel. Clients connect to the root path and pass routing keys via query parameters. bindings: ws: query: type: object properties: apiKey: type: string description: Your NLX API Key. deploymentKey: type: string description: The unique identifier for the AI app deployment. channelKey: type: string description: > The channel identifier. **Must include the language code suffix** (e.g., `xxxxxxxx-en-US`). conversationId: type: string description: Optional ID to resume a specific session. required: - apiKey - deploymentKey - channelKey - apiKey # Client sends messages to Server publish: summary: Send a message operationId: sendMessage description: > Send a conversation turn to the AI app. The payload matches the standard REST ConversationRequest. message: $ref: '#/components/messages/UserMessage' # Client receives messages from Server subscribe: summary: Receive messages operationId: receiveResponse description: > Receive messages from the AI app. Can be a connection acknowledgement or a conversation response. message: oneOf: - $ref: '#/components/messages/ConnectionAck' - $ref: '#/components/messages/AppResponse' components: messages: ConnectionAck: name: ConnectionAck title: Connection Acknowledgement summary: Sent immediately after successful connection. contentType: application/json payload: type: object required: - conversationId properties: conversationId: type: string description: The active session ID for this WebSocket connection. UserMessage: name: UserMessage title: User Message summary: A user turn sent to the bot. contentType: application/json payload: $ref: '#/components/schemas/ConversationRequest' AppResponse: name: AppResponse title: App Response summary: A response from the bot. contentType: application/json payload: $ref: '#/components/schemas/ConversationResponse' schemas: # --------------------------------------------------------- # Request Schemas # --------------------------------------------------------- ConversationRequest: type: object required: - request properties: request: type: object description: The payload containing the user's input data. properties: unstructured: $ref: '#/components/schemas/UnstructuredInput' structured: $ref: '#/components/schemas/StructuredInput' userId: type: string description: Unique identifier for the user. context: type: object description: Key-value map of session attributes. additionalProperties: true UnstructuredInput: type: object description: Input used for free-form natural language processing. required: - text properties: text: type: string description: The raw text of the user utterance. StructuredInput: type: object description: Input used to programmatically invoke specific intents or flows. properties: intentId: type: string description: The ID of the specific intent or flow to trigger. slots: type: array items: $ref: '#/components/schemas/Slot' choiceId: type: string description: The ID of a selected option from a previously presented choice list. uploadIds: type: array description: List of IDs representing uploaded media assets. items: type: string utterance: type: string description: The text representation of the structured input. Slot: type: object properties: slotId: type: string description: Human-readable identifier for the slot. value: oneOf: - type: string - type: number - type: boolean description: The captured value of the slot. topValues: type: array description: List of high-confidence alternative values. items: oneOf: - type: string - type: number - type: boolean choicePayload: type: string description: Additional payload data associated with a selected choice. # --------------------------------------------------------- # Response Schemas # --------------------------------------------------------- ConversationResponse: type: object properties: messages: type: array items: $ref: '#/components/schemas/Message' conversationId: type: string description: The unique session identifier. expirationTimestamp: type: string format: date-time description: Timestamp indicating when the session expires. modalities: type: array items: type: string description: List of available interaction modalities. payload: type: object description: Raw node payload data from the NLU engine. additionalProperties: true metadata: $ref: '#/components/schemas/ResponseMetadata' context: type: object description: Updated session context attributes. additionalProperties: true Message: type: object properties: messageId: type: string description: SHA256 hash identifier for the message. text: type: string description: The text content of the message. type: type: string description: The message type (e.g., 'text', 'multichoice'). choices: type: array description: Available options if the message type is 'multichoice'. items: $ref: '#/components/schemas/MessageChoice' choicesMetadata: type: object properties: source: type: string enum: [Local, Variable] description: The origin source of the choices. metadata: type: object description: Metadata specific to this message. properties: sources: type: array items: $ref: '#/components/schemas/SourceCitation' MessageChoice: type: object properties: choiceId: type: string description: The unique identifier for the choice. choiceText: type: string description: The display text for the choice. SourceCitation: type: object description: A source cited by the generative model. properties: fileName: type: string description: The name of the source file. pageNumber: type: integer description: The page number where content was found. content: type: string description: The snippet of content used. presignedUrl: type: string description: A temporary URL to access the source file. metadata: type: object additionalProperties: true ResponseMetadata: type: object properties: multimodalEnabled: type: boolean description: Indicates if multimodal interaction is active for this session. hasPendingDataRequest: type: boolean description: True if the AI app is awaiting specific data input from the user. intentId: type: string description: The ID of the resolved intent. escalation: type: boolean description: Flag indicating if the conversation requires human escalation. frustration: type: boolean description: Flag indicating if user frustration was detected. incomprehension: type: boolean description: Flag indicating if the NLU failed to understand the user. uploadUrls: type: array items: type: string description: URLs for uploading media, if requested by the flow. isGenerative: type: boolean description: Indicates if the response was generated by LLM/AI logic. feedbackUrl: type: string description: URL for submitting user feedback on this interaction. escalationChannel: type: object description: Configuration for the handoff channel if escalation is triggered. ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nlx.ai/platform/developers/conversation-api/websocket/async-api-spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.