Web Services

Note: Only users with Administrator or Super User rights can access this page.

You can configure web services to be called during conversations. Go to Contents > Web services to access the configuration page. This page allows you to create a REST or SOAP web service from a WSDL. You can choose between the two methods by clicking the Add button and then selecting the type of web service.

The configuration / modification of a web service is divided into several parts:

• Configuration;

• Webservice authentication;

• Webservice headers;

• Parameters

• Result variables;

• Action buttons.

Configuration of a web service

Note : once the service is created, it is not possible to change the type of the web service (REST or SOAP). However, all other fields are editable.

• The Name field allows you to configure the name of the web service, which will be used to call it in the knowledge base.

• The URL field allows you to configure the URL of the web service. It must always be a constant.

• The Cache field allows you to configure the duration of the web service cache. The value 0 deletes the cache mechanism.

• The Timeout field allows you to configure the duration of the web service timeout. The value 0 leaves a standard timeout of an HTTP request.

• The HTTP Method field allows you to configure the type of request: GET / POST / PUT / DELETE. This is especially useful for REST calls.

• The Response Type field allows you to configure the type of answer: XML / text / JSON.

Configuring a certificate for a web service

Configuring a certificate for a webservice is required if you want to ensure the security of online communications between the user/client and the server.

To associate a certificate with a web service, you must first encrypt the certificate key. To do this, go to Preferences > Bot > General. At the bottom of the page you'll find the section "Set a password to encrypt webservice certificates".

The password you choose is final. It cannot be changed or cancelled.

The certificate format must be in PFX (a file format used to encrypt the server certificate, any intermediate certificates and the private key). Once the certificate has been downloaded and the certificate password entered, click on "Save".

Web service authentication

Here you can choose the type of authentication for your web service (OAUTH_2 / HTTP_BASIC). Once selected, you can fill in the fields User name for authentication and Password for authentication. However, these fields may remain empty. They should only be configured if it is really necessary.

Web service headers

This section allows you to add HTTP headers in the call to a service. This is often used for authentication.

Parameters

• The Name field allows you to configure the parameter name.

• The Value field allows you to configure the value of the parameter. If this value is to be retrieved in a dialog, indicate **${capture.**Xxx} with Xxx which is the name of the variable in the dialog.

• The Test Value field allows you to configure a value for the parameter only used when testing the web service on the configuration page (see action buttons). This value is not saved when you leave the page.

For example: In a knowledge, if the question asked by the user is "What's the weather like in Paris?", it is possible to capture the city in indicating in the knowledge "What's the weather like in ${capture.city}?". More complete examples are listed at the bottom of this page.

The parameters are encoded according to the HTTP method: in the URL in GET and in the body of the request in POST / PUT / DELETE.

Result variables

It is possible to configure variables that can be displayed in a dialog with the user. This part will depend on the Response type field.

It is important to note that:

• Variables retrieved from the web service are structured as follows: ${callapi.WebServiceName.variableName};

• Variables retrieved from the dialogue are structured as follows: ${capture.VariableName};

With an XML answer: it is possible to retrieve values from the result by applying XPath or XSLT functions.

Important: XPath or XSLT functions should only return text and never XML to be displayed in dialogs.

With a response of the JSON type: it is possible to recover values from the result by executing javascript.

Important: it is necessary to create at least one javascript function named "dyduParseJSON" which returns a character string or an array of character strings, and whose parameter is the JSON returned by the query (see the REST example at the bottom of the page).

Note that you can also return a general message if the JSON result is invalid. The JSON function should be:

function dyduParseJSON (json, text) {

return {result: json}

}