Jump to: navigation, search

Knowledge API

Introduction

You can use the Knowledge API to retrieve FAQ-related information from a knowledge base, including things like the structure of the knowledge base and its feedback data.

This API consists of four sections:

  • The Session Management API allows you to bundle requests and set your customer ID for your entire session. This is the technical part of the interface, and its concepts and actions are only of interest to developers.
  • The Knowledge Base Operations API lets you explore how many categories your knowledge bases contain, what the categories are, and what specific articles are contained in a knowledge base.
  • You can use the FAQ Retrieval API to ask your knowledge base a question and find the answers, and also to find any documents that are related to this question.
  • The Feedback API gives users a way to send feedback on how useful the responses were.

API Index

Method URI Description
Session Management
PUT /sessions/new/ Creates a new session
GET /sessions/{sessionId} Retrieves information about an existing session by sessionId
POST /sessions/{sessionId} Associates a recognized user with a previously started anonymous session
Knowledge Base Operations
GET /kbs/ Retrieves a list of supported knowledge bases
GET /kbs/{kbId} Retrieves information about a specific knowledge base (including supported languages)
GET /kbs/{kbId}/categories Returns a list of categories
POST /kbs/categories Get federated categories
GET /kbs/{kbId}/{catId}/documents Returns all document previews for the specified category 
GET /kbs/{kbId}/top Returns the top X trending documents
GET /kbs/{kbId}/documents/{docId} Returns the full content of the specified document
Federated knowledge retrieval API
POST /kbs/search performs search for documents that are relevant for the given query (searches in all available knowledge base)
POST /kbs/suggestions retrieve intelliSense suggestions for all available knowledge bases
POST /kbs/{kbId}/documents/{docId}/federatedmorelikethis returns documents with content similar to content of provided document (searches among documents of all available knowledge bases)
POST /kbs/spelling guess spelling correction for the entered query on basis of corpus of all available knowledge base
Knowledge retrieval API
POST /kbs/{kbId}/search performs search for documents that are relevant for the given query (searches in particular knowledge base)
POST /kbs/{kbId}/suggestions retrieve intelliSense suggestions for particular knowledge base
GET /kbs/{kbId}/documents/{docId}/morelikethis Returns content that is similar to the content in the specified document
GET /kbs/{kbId}/spelling Guesses spelling correction for the entered query on basis of particular knowledge base corpus
POST /kbs/documents Browse documents
Feedback API
POST /feedback/{kbId}/noAnswer Marks a query as not having a valid answer in the knowledge base
POST /feedback/{kbId}/documents/{docId}/vote Records the user rating for the document within the query
POST /feedback/{kbId}/documents/{docId}/advancevote Register positive vote for one document and negative vote for all other in provided list
PUT /feedback/{kbId}/documents/{docid}/visit Increments the counter of the viewed document
POST /feedback/unanswered Saves information about federated search request that had no relevant answer (similar to noAnswer, but for federated search)
POST /feedback/{kbId}/documents/{docid}/use Saves information about fact of usage of content of document for answering to user question by agent from agent workspace
PUT /feedback/vote/{voteId} Adds comment and user rating to vote, registered by POST /feedback/vote
POST /feedback/vote/ Registers vote against result of federated search
POST /feedback/{kbId}/documents/{docId}/rating Registers user rating of particular document (with optional search context )
PUT /feedback/interaction Register of fact of receiving new interaction by agent UI
GET /kbs/{kbId}/documents/{docId}/rating Returns document user rating and count of visits
Important
URL identifiers: http://.../res1/{id1}/res2/{id2}...

URL parameters: http://...?{param1}&{param2}

Knowledge API request

All knowledge API requests may contain additional URL parameter “locale” for specifying the language which is used for error messages in case of request failure.

Knowledge API response

The body of every response returned by the Knowledge API has a standard high-level structure:

{
    "statusCode": <execution code>,
        "error": {
            "type": <string>,
            "message": <string>
        },
        "response": {
... },
"sessionId" : <string>
}
Field Type Mandatory Description
statusCode String Yes Execution code of the operation. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR}
error Error Yes Detailed information on the error message. Present only if the operation executed was unsuccessfully.
response complex No Response PAYLOAD for the executed operation. This can be missing if an error occurred or if the method has nothing to report after execution (for example, if an object has been deleted).
sessionId String No Actual session ID (either obtained from the sessionId parameter, or auto-generated [if the method has been called without sessionId parameter])

Global Complex Types

SessionInfo Complex Type

Field Type Mandatory Description
agentId String No ID of identified agent
customerId String No ID of identified customer
globalVisitId String No ID of registered global visit
visitId String No ID of identified visit
_ttl String No Time to live. in form of [n]d, [n]h etc. for example "1h" for one hour.

TTL can be configured only from Config Server(In Options - section "general" , parameter "session-ttl").
This parameter can not be used for new session creating, only for retrieving actual _ttl of session.

KnowledgeBaseListRequest

Field Type Description
Knowledgebases String [] List of knowledge base identifiers

FilterCondition

Field Type Mandatory Description
field String Yes The name of the field to be filtered. Use customFields.<field_name> for referring to a custom field
operator String Yes The operator for expressing the condition. Valid values are:
Operator Type Definition
lt unary less than
le unary less than or equal to
eq unary equals
ge unary greater than or equal to
gt unary greater than
between binary between values
value String Yes for unary Value for comparison in unary conditions (lt, le, eq, ge, gt).
a String Yes for binary Left border for comparison in binary operation (from).
b String Yes for binary Right border for comparison in binary operation (to).

KnowledgeBaseMeta

Field Type Description
id String Knowledge base ID
type String Knowledge type: QNA or ARTICLE
name String Name of knowledge base
active boolean Is this knowledge base active
public boolean Is this knowledge base public or private
customFields CustomFieldMeta[] Configuration of custom fields for this knowledge base
defaultLanguage String Default language for this particular kb
description String Knowledge base description
supportedLanguages String[] Available languages for this knowledge base

CustomFieldMeta

Field Type Description
name String field name
type String field type. Enumeration of {string, numeric, datetime, boolean, enum}
displayName String field display name
defaultValue String field default value

SearchRequest

Field Type Required Description
query String Yes User typed query string
filters FilterCondition [] No List of filters
categories String [] No Set of categories for filtering of documents related to these categories
tags String No Set of tags for extra filtering of documents related to these tags
media String No Instruction for retrieving documents, that related to specified medi type. Empty value means that documents related to any media type will be retrieved.

FederatedSearchRequest

Field Type Required Description
query String Yes User typed query string
filters FilterCondition [] No List of filters
categories String [] No Set of category names for filtering of documents related to these categories.
tags String No Set of tags for extra filtering of documents related to these tags
media String No Instruction for retrieving documents, that related to specified medi type. Empty value means that documents related to any media type will be retrieved.
knowledgebases String [] No List of knowledge base identifiers for restricting scope of search by particular set of knowledge bases.
Warning!
Please take into account that the "knowledgebases" and "categories" filters are applied using the condition "AND", meaning you could face a situation where you might lose a set of documents that do not match both filter conditions at the same time. The easiest way of avoiding this situation is by using only one filter at a time.

RequestKbCategory

Field Type Required Description
kbId String true Knowledgebase identifier
id String true Category identifier

KnowledgeBaseListRequest

Field Type Required Description
knowledgebases String [] No List of knowledgebases to retrieving

DocumentDraftRequest

Field Type Required Description
question String Yes Text of document question
answer String Yes Text of document answer
categories Category [] No List of categories related to draft

Category

Field Type Description
id String Category identifier
kbId String Knowledge base identifier

AdvanceVote

Field Type Required Description
likeDocId String No Id of document for registering positive voting this aganst it
selection String No Range of Id of documents for registering negative voting this aganst them. Includes all id of selection, incluting document of positive voting
request SearchRequest Yes Original search request

KbLanguageMeta

Field Type Description
name String Name of knowledgebase in this particular language
description String Description of knowledgebase in this particular language
defaultFilterConditions FilterCondition [] Set of conditions that filter results retrieved by QNA in this particular language.
schema Enum {basic,nlp} The way which GKS analyzes text in knowledgebase in this particular language. GKS uses Nlp, or natural language processing, to improve retrieving quality. Basic means that GKS utilizes basic elasticsearch functionality during retrieving.
default boolean This flag indicates that this particular language is the default language for this knowledge base.

AccessRuleMeta

Field Type Description
all boolean This flag indicates that the knowledgebase does not restrict access based on skills. Value of true means that GKS will ignore the set of skills in the skills field.
skills String[] The set of skills that restrict user access to knowledgebase. Only users with at least one of the listed skills can access the knowledgebase. This restriction takes effect only if the field all contains a value of false.

BehaviourOptions

This type consists of a set of named complex options, each of which describes knowledgebase behavior from a specific point of view. At the moment the only set of options is the faq options set.

BehaviourOptions.faq

Field Type Description
outOfDomain float Confidence level threshold for casting documents with a low level of relevancy that are obtained from a retrieving selection
numberOfAnswersInPreConfidenceSelection int Relevance scores from document count are used to compute a denominator that calculates the confidence for each obtained document selection.
trendingPeriodInDays int Period in days for computing trends against user activity.
numberOfAnswers int Maximum count of documents in the result selection once QNA retrieving is complete.

Feedback

Comment on this article:

blog comments powered by Disqus
This page was last modified on May 29, 2018, at 12:38.