Asking questions

Questioning vs Querying

Viko supports two types of query - question answering and searching. This document relates to question answering. Read more about question answering vs searching

Contents

1. Ask question
2. Accept/reject answer
3. Forward question

Ask question

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)

Request

POST https://api.viko.ai/v1-beta/{tenancy}/question/ (note: trailing slash)

Request headers

Content-Type application/json (required)
X-Api-Key (required)

Request body

{
  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.

Response

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:

1. Answer & context
2. Answer without context
3. Just the context

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)

Response body

{
  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
}

Example

$ 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
}

Accept/reject answer

Telling Viko whether the user accepts the answer helps improve accuracy.

Request

PATCH https://api.viko.ai/v1-beta/{tenancy}/answer/{id} (note: no trailing slash)

Request headers

Content-Type application/json (required)
X-Api-Key (required)

Request body

{
  accepted: boolean (required)
}

Response

Status: 200 (Ok)

Response body

{
  question: string (required) // original question
  answer: string (optional) // generated answer
  accepted: boolean (required)
}

Example

$ 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 question

Forward the question to an agent. Note: this will implicitly mark the associated answer as rejected.

Request

POST https://api.viko.ai/v1-beta/{tenancy}/forward/{id} (note: no trailing slash)

Request headers

Content-Type application/json (required)
X-Api-Key (required)

Request body

{
  reply_to: email (required) // Who should the agent reply to
}

Response

Status 201 (Created)

Response body

{
  question: string (required) // original question
  reply_to: email (required)
}

Example

$ 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"
}