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/
Parameters: tenancy
Header: X-Api-Key (required)
Content-Type: application/json
Body: JSON object

{
  text: string (required)
  filter: {
    canonical_urls: Array<string> (optional)
    folders: Array<string> (optional)
  } (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. any document with a matching canonical_url or in one of the folders.

Response

The question along with a generated answer (if possible)

Status: 201 (Created)
Body: JSON object

{
  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
  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": {
          "canonical_urls": [
              "https://acme.com/shipping.html"
          ],
          "folders": [
              "shipping"
          ]
      }
  }'

{
  "id": "1",
  "question": "how much is next day shipping?",
  "answer": "$4.95",
  "context": "next day shipping is available for $4.95",
  "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}
Parameters: tenancy, id (question/answer correlation id)
Header: X-Api-Key (required)
Content-Type: application/json
Body: JSON object

{
  accepted: boolean (required)
}

Response

Status: 200 (Ok)
Body: JSON object

{
  id: string (required)
  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 PUT 'https://stub.viko.ai/v1-beta/acme/answer/1' \
  --data-raw '{
    "accepted": true
  }'

{
  "id": "1",
  "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}/question/{id}/forward/
Parameters: tenancy, id (question/answer correlation id)
Header: X-Api-Key (required)
Content-Type: application/json
Body: JSON object

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

Response

Status: 201 (Created)
Body: JSON object

{
  id: string (required)
  question: string (required) // original question
  answer: string (optional) // generated answer
  reply_to: email (required)
}

Example

$ curl --location \
  --header 'X-Api-Key: replaceme' \
  --header 'Content-Type: application/json' \
  --request POST 'https://stub.viko.ai/v1-beta/acme/question/1/forward/' \
  --data-raw '{
    "reply_to": "john.doe@gmail.com"
  }'

{
  "id": "1",
  "question": "how much is next day shipping?",
  "answer": "$4.95",
  "reply_to": "john.doe@gmail.com"
}