@telia-ace/knowledge-serviceclient

The Service Client provides an API for interacting with classic Humany projections. A projection is a URL representing a subset of content (guides, categories, contact methods etc) in a Humany application.

Projection URL Format

The standard format of a Projection URL consists of the root application url followed by the projection name.

https://[application].humany.net/[projection-name]

Create an instance of Service Client

Create an instance by passing the Projection URL as the first constructor argument.

import { ServiceClient } from '@telia-ace/knowledge-serviceclient';

const projection = '[projection-url]';
const serviceClient = new ServiceClient(projection);

Passing additional options

The second constructor argument can be used to pass additional ServiceClientOptions.

`ServiceClientOptions`

Argument	Description	Type
`funnel`	Funnel to report statistics on.	`string`
`client`	Unique ID for the client	`string`
`site`	Site (URI) to report statistics on.	`string`
`paging`	Default paging options	`object`

Comments

Funnel, Client and Site can be overriden by using the options parameter on specific API calls.

Match

Match guides based on a search phrase.

`match(phrase, success, [error])`

Argument	Description	Type
`phrase`	The phrase to match.	`string`
`success`	Callback returning the result.	`function`
`error`	Callback returning a description of the error.	`function`

`match(phrase, options, success, [error])`

Argument	Description	Type
`phrase`	The phrase to match.	`string`
`options`	Additional matching options	`MatchingOptions`
`success`	Callback returning the result.	`function`
`error`	Callback returning a description of the error.	`function`

`MatchingOptions`

Argument	Description	Type
`statisticsDisabled`	Whether statistics should be reported for the request.	`boolean` (default: false)
`categoryId`	Limit the matching to the specified category	`number`

Example

serviceClient.match('hello world', (matchResult) => {
  console.log('matched guides:', matchResult.Matches);
});

Get categories

`getCategories(success, [error])`

Argument	Description	Type
`success`	Callback returning the result.	`function`
`error`	Callback returning a description of the error.	`function`

`getCategories(options, success, [error])`

Argument	Description	Type
`options`	Additional matching options	`CategoriesOptions`
`success`	Callback returning the result.	`function`
`error`	Callback returning a description of the error.	`function`

`CategoriesOptions`

Argument	Description	Type
`phrase`	Get categories containging guides matching a phrase	`string`
`categoryId`	Limit the matching to the specified category	`number`
`expand`	Possible values: `'none'`, `'children'`, `'descendants'`	`string`

Example

serviceClient.getCategories((categoryResult) => {
  console.log('all categories:', categoryResult.Children);
});

Get guide

`getGuide(id, success, [error])`

Argument	Description	Type
`id`	Guide ID.	`number`
`success`	Callback returning the result.	`function`
`error`	Callback returning a description of the error.	`function`

`getGuide(id, options, success, [error])`

Argument	Description	Type
`id`	Guide ID.	`number`
`options`	Additional guide options.	`GuideOptions`
`success`	Callback returning the result.	`function`
`error`	Callback returning a description of the error.	`function`

`getGuide(id, connectionKey, success, [error])`

Argument	Description	Type
`id`	Guide ID.	`number`
`connectionKey`	A connection key (part of dialog) to get.	`string`
`success`	Callback returning the result.	`function`
`error`	Callback returning a description of the error.	`function`

`getGuide(id, connectionKey, options, success, [error])`

Argument	Description	Type
`id`	Guide ID.	`number`
`connectionKey`	A connection key (part of dialog) to get.	`string`
`options`	Additional guide options.	`GuideOptions`
`success`	Callback returning the result.	`function`
`error`	Callback returning a description of the error.	`function`

`GuideOptions`

Argument	Description	Type
`statisticsDisabled`	Whether statistics should be reported for the request.	`boolean` (default: false)

Comments

If the Guide is not intended to be displayed as a result of a previous match statistics should be disabled.

Give feedback on guide

`giveFeedback(id, connectionKey, feedbackType, [success, error])`

Argument	Description	Type
`id`	Guide ID.	`number`
`connectionKey`	A connection key (part of dialog) to give feedback on.	`string`
`feedbackType`	Type of feedback to give (`Positive` or `Negative`).	`string`

Accessing the Service Client from a plugin

For implementations running version 4 you can author a plugin and access the current Service Client through the container under the key 'matchingClient'. The value must be resolved asynchronously as in the example below.

import { Plugin } from '@telia-ace/knowledge-widget-core';

class MyPlugin extends Plugin {
  initialize() {
    this.container.getAsync('matchingClient').then((matchingClient) => {
      // use 'matchingClient' here
    });  
  }
}