# Models

## The ConversationRequest object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The UnstructuredInput object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The StructuredInput object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The Slot object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The ConversationResponse object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"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 (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."}}}}}}
```

## The Message object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"schemas":{"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}}}}}}
```

## The MessageChoice object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"schemas":{"MessageChoice":{"type":"object","properties":{"choiceId":{"type":"string","description":"The unique identifier for the choice."},"choiceText":{"type":"string","description":"The display text for the choice."}}}}}}
```

## The SourceCitation object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"schemas":{"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}}}}}}
```

## The ResponseMetadata object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```