Asking questions, accepting & rejecting answers
Last updated: 28 October 2022
Viko supports two types of query - question answering and searching. This document relates to question answering. Read more about question answering vs searching
The examples in this document use the stubbed endpoint. Remember to switch over to the real endpoint !
Ask a question e.g. “how much is next day shipping?“. Viko will try to generate a direct answer.
Filters can be applied to restrict the document sources (context)
POST https://api.viko.ai/v1-beta/{tenancy}/question/ (note: trailing slash)
Content-Type application/json (required)
X-Api-Key (required)
{
text: string (required)
filter: {
folders: Array<string> (required)
} (optional)
}
Note: The context used to answer a question is a union of all those documents matching a filter. Put another way - we apply an implicit OR clause to filters i.e. documents within any of the specified folders.
Viko will return the question along with a generated answer (if possible).
Note: Viko will always return a JSON document. You should check the answer
and context
fields to understand if Viko was able to answer the question.
Viko may return:
Viko may also return a link to a document (the link
field)
The response will include an id
field. This identifier acts as a correlation id, allowing you to subsequently mark the answer as accepted, or forward it to an agent for handling.
Status: 201 (Created)
{
id: string (required) // generated correlation id. Required for accept/reject/forward calls
question: string (required) // echoed back
answer: string (optional) // generated answer
context: string (optional) // additional context (text) around the answer
link: string (optional)
confidence: float (required) // 0 to 1
}
$ curl \
--header 'X-Api-Key: replaceme' \
--header 'Content-Type: application/json' \
--request POST 'https://stub.viko.ai/v1-beta/acme/question/' \
--data-raw '{
"text": "how much is next day shipping?",
"filter": {
"folders": [
"shipping"
]
}
}'
{
"id": "1",
"question": "how much is next day shipping?",
"answer": "$4.95",
"context": "next day shipping is available for $4.95",
"link": "https://acme.com/shipping.html",
"confidence": 0.85
}
Telling Viko whether the user accepts the answer helps improve accuracy.
PATCH https://api.viko.ai/v1-beta/{tenancy}/answer/{id} (note: no trailing slash)
Content-Type application/json (required)
X-Api-Key (required)
{
accepted: boolean (required)
}
Status: 200 (Ok)
{
question: string (required) // original question
answer: string (optional) // generated answer
accepted: boolean (required)
}
$ curl \
--header 'X-Api-Key: replaceme' \
--header 'Content-Type: application/json' \
--request PATCH 'https://stub.viko.ai/v1-beta/acme/answer/1' \
--data-raw '{
"accepted": true
}'
{
"question": "how much is next day shipping?",
"answer": "$4.95",
"accepted": true
}
Forward the question to an agent. Note: this will implicitly mark the associated answer as rejected.
POST https://api.viko.ai/v1-beta/{tenancy}/forward/{id} (note: no trailing slash)
Content-Type application/json (required)
X-Api-Key (required)
{
reply_to: email (required) // Who should the agent reply to
}
Status 201 (Created)
{
question: string (required) // original question
reply_to: email (required)
}
$ curl \
--header 'X-Api-Key: replaceme' \
--header 'Content-Type: application/json' \
--request POST 'https://stub.viko.ai/v1-beta/acme/forward/1' \
--data-raw '{
"reply_to": "john.doe@gmail.com"
}'
{
"question": "how much is next day shipping?",
"reply_to": "john.doe@gmail.com"
}