Jump to: navigation, search

Feedback

The Feedback API gives users a way to send feedback on how useful the responses were.

Important
The Feedback covered by this API conveys how relevant specific answers have been in response to the search questions. This kind of information is not available for browsing articles based on categories.

Authorization

The operations carried out by the Feedback API can be accessed by all roles.

Knowledge Feedback API

Common data structures

UnansweredRequestBody

Field Type Description
question String QNA question
answer String QNA question
categories RequestKbCategory related categories
knowledgebases String [] Related knowledgebases

FederatedVoteDocument

Field Type Description
KbId String Identifier of knowledgebase
docId String Identifier of document

FederatedVoteRequest

Field Type Description
selection DocumentVote [] List of documents in voting selection
like DocumentVote The one document that must be voted positive against another documents from list of "selection" that must be voted as negative.
request SearchRequest Search request used for obtaining of "selection".

RatingRequest

Field Type Description
comment String Text of comment
rating integer Rating value. 1..5

HistoryRecordId Complex Type

Field Type Description
recordId String Identifier of record in history storage

No Answer

Description Marks a query as not having a valid answer in the knowledge base
URL /feedback/{kbId}/noAnswer
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL IDs
Parameter Type Description
{kbId} String Knowledge base ID
URL parameters
Parameter Type Required Default Description
lang String Yes "_default" Language ID
subTenantId String No Sub tenant identifier
sessionId String No Session ID
Request Search query, as described in "Search for answers" section
Parameter Type Required Default Description
question String Yes User question (query)
categories String[] No Related categories
Response RecordIdResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Register Vote

Description Records the user rating for the document within the query
URL /feedback/{kbId}/documents/{docId}/vote
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL IDs
Parameter Type Description
{kbId} String Knowledge base ID
{docId} String Document ID
URL Parameters
Parameter Type Required Default Description
relevant Boolean No true Was the search result relevant?
lang String No "_default" Language ID
String No Sub tenant identifier
sessionId String No Unique session ID
Request SearchRequest
Response RecordIdResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Advance Register Vote

Description Records user rating for the document within query
URL /feedback/{kbId}/documents/{docId}/advancevote
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL IDentifiers
Parameter Type Description
{kbId} String Knowledgebase identifier
{docId} String Document identifier
URL Parameters
Parameter Type Required Default Description
relevant Boolean No "_default" Whether the search result was relevant?
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request AdvanceVote
Response RecordIdResponse
Notes In case of success returns payload in response field of "response" of declared structure.

Register visit

Description records user rating for the document within query
URL /feedback/{kbId}/documents/{docid}/visit
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL IDentifiers
Parameter Type Description
{kbId} String Knowledgebase identifier
{docId} String Document identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request SearchRequest
Response RecordIdResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Register unanswered federated search request

Description Saves information about federated search request that had no relevant answer (similar to noAnswer, but for federated search)
URL /feedback/unanswered
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL IDentifiers
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request SearchRequest
Response RecordIdResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Register usage of document content

Description Saves information about fact of usage of content of document for answering to user question by agent from agent workspace
URL /feedback/{kbId}/documents/{docId}/use
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
kbId String Knowledge base identifier
docId String Document identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request SearchRequest
Response RecordIdResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Extend feedback with rating and comment

Description Adds comment and user rating to vote, registered by POST /feedback/vote
URL /feedback/vote/{voteId}
Method PUT
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
voteId String Record identifier, obtained as response after executing POST /feedback/vote
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request RatingRequest
Response RecordIdResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Federated vote

Description Registers vote against result of federated search
URL /feedback/langs/{lang}/vote/
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Identifier Type Description
lang String Language identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request FederatedVoteRequest
Response RecordIdResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Register user rating for document

Description Registers user rating of particular document (with optional search context )
URL /feedback/{kbId}/documents/{docId}/rating
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
kbId String Knowledge base identifier
docId String document identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request RatingRequest
Response RecordIdResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Register Vote for Query Results

Description Tallies request.likeDocId as a positive vote, as well as all of the documents from request.selection, excluding request.likeDocId as negative in relation to the request.
URL /feedback/{kbId}/documents/{docId}/advancevote
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL IDs
Parameter Type Description
{kbId} String Knowledge base ID
{docId} String Document ID
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language ID
sessionId String No Unique session ID
Request AdvanceVote
Field Type Required Description
likeDocId String Yes ID of document for which a positive vote is being registered
selection String [] No ID ranges of documents for which a negative vote is being registered. Includes all IDs in the selection, including those documents for which a positive vote is being registered.
request SearchRequest Yes Original search request.
Response HistoryRecordId
Notes Returns id of the history record that was created as a result of the advance vote.

Register Visit

Description Increments the counter of the viewed document
URL /feedback/{kbId}/documents/{docid}/visit
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL IDs
Parameter Type Description
{kbId} String Knowledge base ID
{docId} String Unique document ID
URL parameters
Parameter Type Required Default Description
lang String No "_default" Language
sessionId String No Unique session ID for history tracking
Request SearchRequest
Response HistoryRecordId
Notes Returns id of the history record that was created as a result of the visit registering.

Add user comment to particular vote

VoteComment Complex Type

Field Type Description
comment String Text of user comment

Add user comment to particular vote

Description Adds text of user comment to record of particular vote
URL /vote/{voteId}/
Method PUT
Response Content-Type application/json
Role Any
URL IDs
Parameter Type Description
{voteId} String Identifier of the record in history storage, obtained as a result of registering the vote.
URL parameters -
Request Body VoteComment
Response RecordIdResponse
Notes Returns the same record id that was sent as the voteId in the parameters.

Agent document authoring API

Retrieve list of suggested documents from all available knowledge bases

Description Retrieves list of suggested documents from all available knowledge bases
URL /kbs/langs/{lang}/drafts
Method GET
Request Content-Type
Response Content-Type application/json
Role Agent
URL Identifiers
Identifier Type Description
lang String Language identifier
URL Parameters
Parameter Type Required Default Description
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
status String no Status of authored document (created, accepted, rejected)

by default - all authored documents

from int No 0 Start position for pagination, default=0
size int No 10 Size of page for pagination, default=10
startDate StringDate yyyy-MM-dd HH:mm:ss No very start Begin of period for retrieving
endDate StringDate yyyy-MM-dd HH:mm:ss No Today End of period for retrieving
knowledgebases String [] No List of knowledge bases; by default - all
Request
Response
Field Type Description
count int total count of documents in selection (pagination-independent)
page Pagination pagination information
documents AuthoredDocumentEntry [] result selection of document
categories CategoryFacetItem[] Facet selection of categories, related to selected documents set
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Retrieve list of suggested documents from particular knowledge base

Description Retrieves list of suggested documents from all available knowledge bases
URL /kbs/{kbId}/drafts
Method GET
Request Content-Type
Response Content-Type application/json
Role Agent
URL Identifiers
Parameter Type Description
kbId String Knowledge base identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
status String no Status of authored document (created, accepted, rejected)

by default - all authored documents

from int No 0 Start position for pagination, default=0
size int No 10 Size of page for pagination, default=10
startDate String No Left margin for filtering iytems by date of creation. Receives date in form of string of format "yyyy-MM-dd HH:mm:ss"
endDate String No Right margin for filtering iytems by date of creation. Receives date in form of string of format "yyyy-MM-dd HH:mm:ss"
Request
Response
Field Type Description
count int total count of documents in selection (pagination-independent)
page Pagination pagination information
documents AuthoredDocumentEntry [] result selection of document
categories CategoryFacetItem[] Facet selection of categories, related to selected documents set
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Retrieve list of suggested documents from set of knowledge bases

Description Retrieves list of suggested documents from set of knowledge bases.
URL /kbs/{kbId}/drafts
Method GET
Request Content-Type
Response Content-Type application/json
Role Agent
URL Identifiers
URL Parameters
Parameter Type Required Default Description
lang String No "_default" language
subTenantId String No Sub tenant identifier
sessionId String No Unique session identifier for history tracking
knowledgebases String No Set of knowledge bases identifiers for retrieving suggested documents
status String No Status of authored document (created, accepted, rejected)

Default= all authored documents

from int No 0 Start position for pagination

Default= 0

size int No 10 Size of page for pagination

Default= 10

startDate String No Left margin for filtering iytems by date of creation. Receives date in form of string of format "yyyy-MM-dd HH:mm:ss"
endDate String No Right margin for filtering iytems by date of creation. Receives date in form of string of format "yyyy-MM-dd HH:mm:ss"
Request
Response
Field Type Description
count int total count of documents in selection (pagination-independent)
page Pagination pagination information
documents AuthoredDocumentEntry [] result selection of document
categories CategoryFacetItem[] Facet selection of categories, related to seslected documents set

Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Create suggested document

Description Creates suggested document
URL /kbs/{kbId}/drafts
Method POST
Request Content-Type application/json
Response Content-Type application/json
Role Agent
URL Identifiers
Parameter Type Description
kbId String Knowledge base identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request DocumentDraftRequest
Response RecordIdResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.


Mark suggested document as processed

Description Marks suggested document as processed
URL /kbs/{kbId}/drafts/{draftId}
Method PATCH
Request Content-Type
Response Content-Type application/json
Role Agent
URL Identifiers
Parameter Type Description
kbId String Knowledge base identifier
draftId String Document draft identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
documentId String No Identifier of the created document if document was created on base of draft
Request
Response RecordIdResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Agent favorite documents processing

Retrieve list of favorites documents from all available knowledge bases

Description Retrieves list of favorites documents from all available knowledge bases
URL /kbs/documents/langs/{lang}/favorites
Method POST
Request Content-Type
Response Content-Type application/json
Role Agent
URL Identifiers
Identifier Type Description
lang String Language identifier
URL Parameters
Parameter Type Required Default Description
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
from int No 0 Start position for pagination, default=0
size int No 10 Size of page for pagination, default=10
knowledgebases String [] No List of knowledge bases; by default - all
Request body
Identifier Type Description
knowledgebases String [] List of knowledge bases

Default= all

Response
Field Type Description
count int total count of documents in selection (pagination-independent)
page Pagination pagination information
documents AuthoredDocumentEntry [] result selection of document
categories CategoryFacetItem[] Facet selection of categories, related to selected documents set
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Retrieve list of favorites documents from particular knowledge base

Description Retrieves list of favorites documents from particular knowledge base
URL /kbs/{kbId}/favorites
Method GET
Request Content-Type
Response Content-Type application/json
Role Agent
URL Identifiers
Parameter Type Description
kbId String Knowledge base identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
from int No 0 Start position for pagination, default=0
size int No 10 Size of page for pagination, default=10
Request
Response
Field Type Description
count int total count of documents in selection (pagination-independent)
page Pagination pagination information
documents AuthoredDocumentEntry [] result selection of document
categories CategoryFacetItem[] Facet selection of categories, related to selected documents set
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Add document to favorites

Description Adds document to favorites
URL /kbs/{kbId}/documents/{docId}/favorites
Method POST
Request Content-Type
Response Content-Type application/json
Role Agent
URL Identifiers
Parameter Type Description
kbId String Knowledge base identifier
docId String Document identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request
Response KnowledgeFavoritesResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Remove document from favorites

Description Removes document from favorites
URL /kbs/{kbId}/documents/{docId}/favorites
Method DELETE
Request Content-Type
Response Content-Type application/json
Role Agent
URL Identifiers
Parameter Type Description
kbId String Knowledge base identifier
docId String Document identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request
Response KnowledgeFavoritesResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Other

Common Data Structures

DocumentRateResponse =

Field Type Description
avgRate float Average user rate
rateCounters int [5] Number of user votes for each document rate value:

rateCounters[0] - counter for rate=1 star
....
rateCounters[4] - counter for rate=5 stars

visits int count of user visits


Register user rating for document

Description Registers user rating of particular document (with optional search context )
URL /{kbId}/documents/{docId}/rating
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
kbId String Knowledge base identifier
docId String Document identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request RatingRequest
Response DocumentRateResponse
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.


Register of fact of receiving new interaction by agent UI

Description Creates history record of type INTERACTION
URL /feedback/interaction
Method PUT
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
URL Parameters
Parameter Type Required Default Description
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request
Response RecordId
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

This page was last modified on June 22, 2017, at 04:52.

Feedback

Comment on this article:

blog comments powered by Disqus