# 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},"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."}}}}}}
```

## 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., '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."}}}}}}
```

## 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":"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}}}}}}
```

## 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."},"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."}}}}}}
```

## The ContextRequest object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"schemas":{"ContextRequest":{"type":"object","required":["conversationId","context"],"properties":{"conversationId":{"type":"string","description":"The conversation ID for this session."},"context":{"type":"object","description":"Structured context data. Additional custom context keys are allowed.","additionalProperties":true,"properties":{"nlx:vpContext":{"type":"object","properties":{"uri":{"type":"string","description":"The current page URI path."},"actions":{"type":"array","description":"Available actions the user can perform.","items":{"$ref":"#/components/schemas/VoicePlusContextAction"}},"fields":{"type":"array","description":"List of interactive form fields on the page.","items":{"$ref":"#/components/schemas/VoicePlusContextField"}},"destinations":{"type":"array","description":"List of navigation destinations.","items":{"type":"string"}},"scopes":{"type":"array","description":"List of scope tags applicable to the current interaction.","items":{"type":"string"}}}}}}}},"VoicePlusContextAction":{"type":"object","required":["action","description"],"properties":{"action":{"type":"string","description":"The identifier of the action."},"description":{"type":"string","description":"Description of what the action does."},"input":{"type":"object","description":"Additional context describing user specific input related to the action."},"schema":{"type":"object","description":"Optional JSON schema describing parameters for the action.","additionalProperties":true}}},"VoicePlusContextField":{"type":"object","required":["id","name","type"],"properties":{"id":{"type":"string","description":"Unique ID of the form field."},"name":{"type":"string","description":"Human readable name of the field."},"type":{"type":"string","description":"Input type (e.g., text, select, number)."},"description":{"type":"string","description":"Contextual description for the AI."},"placeholder":{"type":"string","description":"UI placeholder text."},"value":{"nullable":true,"description":"Current value of the field."},"options":{"type":"array","description":"Available options for select/radio fields.","items":{"$ref":"#/components/schemas/VoicePlusContextFieldOption"}}}},"VoicePlusContextFieldOption":{"type":"object","properties":{"value":{"nullable":true,"description":"The underlying value of the option."},"text":{"nullable":true,"description":"The display text of the option."},"selected":{"type":"boolean","description":"Whether this option is currently selected."}}}}}}
```

## The VoicePlusContextAction object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"schemas":{"VoicePlusContextAction":{"type":"object","required":["action","description"],"properties":{"action":{"type":"string","description":"The identifier of the action."},"description":{"type":"string","description":"Description of what the action does."},"input":{"type":"object","description":"Additional context describing user specific input related to the action."},"schema":{"type":"object","description":"Optional JSON schema describing parameters for the action.","additionalProperties":true}}}}}}
```

## The VoicePlusContextField object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"schemas":{"VoicePlusContextField":{"type":"object","required":["id","name","type"],"properties":{"id":{"type":"string","description":"Unique ID of the form field."},"name":{"type":"string","description":"Human readable name of the field."},"type":{"type":"string","description":"Input type (e.g., text, select, number)."},"description":{"type":"string","description":"Contextual description for the AI."},"placeholder":{"type":"string","description":"UI placeholder text."},"value":{"nullable":true,"description":"Current value of the field."},"options":{"type":"array","description":"Available options for select/radio fields.","items":{"$ref":"#/components/schemas/VoicePlusContextFieldOption"}}}},"VoicePlusContextFieldOption":{"type":"object","properties":{"value":{"nullable":true,"description":"The underlying value of the option."},"text":{"nullable":true,"description":"The display text of the option."},"selected":{"type":"boolean","description":"Whether this option is currently selected."}}}}}}
```

## The VoicePlusContextFieldOption object

```json
{"openapi":"3.0.3","info":{"title":"NLX Conversation API","version":"1.0.0"},"components":{"schemas":{"VoicePlusContextFieldOption":{"type":"object","properties":{"value":{"nullable":true,"description":"The underlying value of the option."},"text":{"nullable":true,"description":"The display text of the option."},"selected":{"type":"boolean","description":"Whether this option is currently selected."}}}}}}
```