> 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/rest/conversation.md).

# 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","description":"Standard authentication for Conversation endpoints."}},"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},"environment":{"type":"string","enum":["development","production"],"description":"The environment context for the request."}}},"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., 'text', 'voice')."},"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":"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."},"externalProcessingEnabled":{"type":"boolean","description":"Indicates if external processing hooks were active."},"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"}}}},"400":{"description":"Bad Request - Invalid schema or missing required fields"},"401":{"description":"Unauthorized - Invalid API Key"},"500":{"description":"Internal Server Error"}}}}}}
```


---

# 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:

```
GET https://docs.nlx.ai/platform/developers/conversation-api/rest/conversation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.