Skip to content
Unless Docs

Sending a question (realtime)

POST
/api/v1/ai/query

The query endpoint always gives you a chat-data object that has the original question and the response it generated. Normally, you would use this object to show the response in your view. It’s important to use the chatDataJson property when you ask any more questions to make sure the conversation history is kept correctly.

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
x-api-key
required
string

Your API key from account settings.

Request Body required

Section titled “Request Body required ”
object
query
required

The question you want to send to the AI.

string
accountId
required
string
apiKey
required
string
websiteId
required

The website ID you trained the AI on.

string
visitorId
required

An unique identifier for your visitor.

string
sessionId
required

An unique identifier for the current session.

string
conversationName

In case you have multiple topics, you can give each a different name.

string
segmentId

Optional segment to search in.

string
audienceId

You can provide an audienceId to be used for content lookup. Use comma-separated id’s to supply multiple.

string
metadata

Send an additional metadata object that we’ll show in the dashboard.

string
messageFormat

You can set this value to ‘html’ if you want the messages formatted as html instead of markdown.

string
default: md
Allowed values: md html
skipLanguageDetection

The AI will validate if the question asked is in the same language as the current conversation language. If that doesn’t match, the AI will send back a command to switch the conversation language. You can turn off this language check using this property, which means the AI will always respond in the conversation language.

boolean
chatDataJson
required

Our chat-data wrapper for managing history. See the response at the right for an example. To maintain a proper history, which is important for follow-up questions and logging, you should supply this with every query (except the first query).

string

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful response containing updated chat data.

Conversation state object returned by query endpoints.

object
history

Array of conversation turns.

Array<object>
object
type
string
timestamp
integer
0
uuid
string
hidden
boolean
default: true
sender
string
message
string
metadata
Array<object>
object
languageCode
string
showMetadata
boolean
default: true
canGetFeedback
boolean
default: true
feedback
string
metadata

Arbitrary metadata associated with the conversation.

object
toolsetName
string
nullable
personalizationId
string
sessionId
string
conversationName
string
nullable
conversationId
string
Example
{
  "history": [
    {
      "type": "message",
      "timestamp": 1687956110772,
      "uuid": "57c1968c-1b49-48d5-a484-ed299e609b8a",
      "hidden": false,
      "sender": "user",
      "message": "What does Unless do?",
      "metadata": [],
      "languageCode": "en",
      "showMetadata": false,
      "canGetFeedback": false,
      "feedback": ""
    },
    {
      "type": "message",
      "timestamp": 1687956112605,
      "uuid": "5aa331df-1e6d-4ee2-b6aa-93176e521469",
      "hidden": false,
      "sender": "bot",
      "canGetFeedback": true,
      "message": "Unless is a tool that allows companies to create highly personalized and compelling landing pages to highlight their benefits compared to competitors. It also offers AI training to become an expert in a company's product and provides conversational UI components.",
      "metadata": [
        {
          "title": "Rapid experimentation",
          "isPublic": true,
          "isUsedForAnswer": true,
          "source": "https://unless.com/en/blog/customer-cases/rapid-experimentation-at-prenatal/",
          "documentId": "4c0cbe48-bd8b-403e-bbad-3d16a9c679c9",
          "stableId": "c37310599c08a2a2d5295fbd98c42a34",
          "trainingDataId": "1e61e2e6-8b3f-4b90-8703-a40aa6d7783f"
        }
      ],
      "showMetadata": false,
      "feedback": ""
    }
  ],
  "metadata": {},
  "toolsetName": null,
  "personalizationId": "",
  "sessionId": "23d1b8d1-64f5-4dd2-8122-73e56d0c78ff",
  "conversationName": null,
  "conversationId": "e796d388-ddb3-4ab6-9891-06f2e4dd16cb"
}