# Conversation

Operations related to processing conversation turns.

## Process a conversation turn

> Main endpoint for conversational applications. Sends a user request to the specific AI app deployment and channel.

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"tags":[{"name":"Conversation","description":"Operations related to processing conversation turns."}],"servers":[{"url":"https://apps.nlx.ai","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"nlx-api-key"}},"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"}}},"conversationId":{"type":"string","nullable":true,"description":"Unique identifier for the conversation session. Auto-generated if omitted."},"userId":{"type":"string","description":"Unique identifier for the user. Auto-generated if omitted."},"context":{"type":"object","description":"Key-value map of session attributes (limit 2000 chars). Restricted to platform-defined attributes.","additionalProperties":true},"stream":{"type":"boolean","description":"Enables Streamable HTTP","default":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 associated with this request.","items":{"type":"string"}},"utterance":{"type":"string","description":"The text representation of the structured input, if applicable."}}},"Slot":{"type":"object","properties":{"slotId":{"type":"string","description":"Human-readable identifier for the slot (e.g., 'CardType', 'Location')."},"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 for this slot.","items":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"choicePayload":{"type":"string","description":"Additional payload data associated with a selected choice."}}},"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 (e.g., Card, PaymentSummary, Carousel)."},"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 (excludes system keys like userId/conversationId).","additionalProperties":true}}},"Message":{"type":"object","properties":{"messageId":{"type":"string","description":"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."}}}}},"paths":{"/c/{deploymentKey}/{channelKey}":{"post":{"tags":["Conversation"],"summary":"Process a conversation turn","description":"Main endpoint for conversational applications. Sends a user request to the specific AI app deployment and channel.","operationId":"processConversation","parameters":[{"name":"deploymentKey","in":"path","required":true,"schema":{"type":"string"},"description":"The unique key identifying the AI app deployment."},{"name":"channelKey","in":"path","required":true,"schema":{"type":"string"},"description":"The unique key identifying the specific channel.  **Must include the language code suffix** (e.g., `-en-US`, `-es-MX`).\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationRequest"}}}},"responses":{"200":{"description":"Successful conversation response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResponse"}},"text/event-stream":{"description":"Server-Sent Events (SSE) stream.  If 'stream: true' is passed in the request, the response will be streamed  as a series of 'data' events containing conversation chunks.\n","schema":{"$ref":"#/components/schemas/ConversationResponse"}}}},"400":{"description":"Bad Request - Invalid schema or missing required fields"},"401":{"description":"Unauthorized - Invalid API Key"},"500":{"description":"Internal Server Error"}}}}}}
```