With our SOAP API integration, you can configure a chatbot to respond based on the result of an API call; via slot filling, either use part of the API call result in a response or make a decision based on it.
We support basic access and bearer token authentication; custom header values, and XPath for extracting entities from responses.
To test extraction of your responses with XPath, we recommend the online tool, XPath online real-time tester, or simply in line in our API configuration view.
Configuring a SOAP API call
Navigate to the API Call configuration page via Build -> Actions -> API Calls and click on the "Create New SOAP API Call" button.
Description of the fields:
- SOAP API Call Name - Enter a descriptive name for this API call, it will be used to identify this call when you use it in the dialog manager.
- Method - The HTTP method for the request. We currently support GET and POST.
- SOAP API Endpoint URL - The address of the request, including the scheme (http or https). If the endpoint requires IP whitelisting, the requests will be sent from the IP: 34.90.135.186.
- URL Parameters* - The query string in addition to the URL.
- Headers* - The request headers. By default, we automatically add Content-Type: text/xml; charset=utf-8 to all calls unless form data is selected, then it will be Content-Type: application/x-www-form-urlencoded instead
- Body* - The body of the SOAP call, i.e. the content to post to the end point. This is only available for the POST method.
- Use form data JSON instead of XML - when this is checked, we shall use form data instead of XML body for this call. Select this if your API is using form data, and provide the form data key value pairs in the form of a JSON structure in the Body input instead.
- Authorization* - Optional authentication mechanism; we currently support basic and bearer token. If these do not meet the end point, see if a custom header entry will work.
The fields with (*) supports handlebar (double curly braces) for slot filling. These values can be set when the API configuration is used in the dialog.
- For headers, only the value can be replaced by slot filling.
- For Authorization, only Bearer token can be replaced by slot filling.
Once the required values are entered, the "Test" becomes available and you can test the API call:
Fill in any handlebar values you have for the test, in this case the number to convert to text:
And the response of the call will be shown in the screen:
Extracting entities from SOAP API response
After successfully configuring an API call, the response from the call can be used as entities by using XPath in the API configuration screen. XPath is an expression language designed to support the query or transformation of XML documents. Read more about XPath here.
Description of fields under Extraction Rules:
- Entity: The name of the entity to store the extracted value
- Extraction Path: The XPath expression to extract the entity from
- Evaluation results: the extraction result of the XPath evaluated against the last test result of the SOAP call. This will only extract string values out of response. If the provided XPath does not resolve to a single string value i.e. a node, it will "Object{}" instead.
In the above example, both numberText and badXPath will be set to "forty two". It will be available as an entity for slot filling in the dialog manager.
Due to how XPath works with XML namespaces, you will need to use "local-name()" to match for any namespace. For the example above, we cannot use the following XPaths to match the result:
- //NumberToWordsResult/text()
- //m:NumberToWordsResult/text()
But instead need to use:
//*["NumberToWordsResult"=local-name()]/text()
In order to loosely match the result.
Entity setter
In case the format of an entity is extracted from any API, it could be that the information is not user friendly, with the entity setter, we can reshape the output to facilitate the interaction for the end-user.
Read more about using the entity setter in this article.