# 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."}}}}}} ``` --- # Agent Instructions: 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/voice+-api/track/models.md?ask= ``` 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.