Concept of service requests

Client can provide additional functionality to conversational service e.g. providing weather forecast, name days or news.

This functionality is requested from dialog by setting to a name of the particular functionality, possible arguments to "context.request.args" and usually by setting skip_user_input:true (if we do not request extra user input as we usually do not).

Request template:

"context": {
        "request": {
                "name": string,
                "args": any

Service request handlers are called in app.js:doOnClient() if a client side request is returned from dialog.

There can be other client functionality not available directly from dialog or a services which are used or integrated together by add-ons. They are stored in Services subdirectory.

Request handler

Request handler is a function that responds to the request passed in context as shown above. Results are placed directly to the params.payload.context.

 * @param params	object that holds all data needed
 * @param callback 	call this function when complete
export interface RequestHandler {
	(params: RequestHandlerParams, callback: {(error: any): void; (): void;}): void

Mind that request handler should be just initiating the operation and finishing quickly. It is however having asynchronous callback fwhich is called when operation is finally completed (as usual in javascript).


/** Parameters passed to request handler with each call */
interface RequestHandlerParams {
	/** This is last request from browser containing configurations e.g. keys and credentials for web services) */
	config: ClientConfig;
	/** args field of the request. Shortcut to payload.context.request.args. */
	args: any;
	/** The whole object passed passed from browser. Also a prefilled request to dialog service. */
	payload: BrowserToServerPayload;

For more details about data structures see Data types

Creating custom service requests

Service request are implemented as Addons. See addons for more detail.

The name of the service request addon file should be the same as it responds to.

Template addon with one service request handler:

import * as ClientV2 from "../ClientV2";
export = <ClientV2.Addon>function (addonParams: ClientV2.AddonParams) {
  addonParams.registerRequestHandler ("helloWorldRequestName", function (params: ClientV2.RequestHandlerParams, callback) {
    params.payload.context.result = "hello world!";

Context data size limit

Service request handlers will often provide some data by assigning object to a context variable as seen in examples above. Without unassigning these data, context would only grow until conversation store limit is reached. Therefore, clientv2 automaticaly deletes keys that were assigned by request handlers to reduce size of context. Large and old keys in context object are more likely to be removed.

Message payload size limit is configured in config tab by request_size_limit key as a number of bytes.

This functionality is provided by forgetting addon.