Async API Spec
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.Last updated