Call API is an extension of AIML 2.1, built into the Pandorabots platform. It allows bot developers to build API calls to external servies into their AIML. The AIML is interpreted as normal, and the calls are sent via the Pandorabots platform. Responses are then received by the Pandorabots platform and passed back to the bot, which interprets the response via AIML. Call API is not yet standardized, so it may not be portable to other AIML interpreters.
Call API has three primary purposes: to get dynamic data from an external source that you can’t program into your bot (e.g. the weather or stock ticker price), to extend the knowledge and capabilites of your bot by referencing external sources (e.g. news site or Wikipedia), or to save information from users in a database that you control as part of a larger service (e.g. inputing location details for a catering event).
This is the wrapping tag for the Call API function. Everything happening with the API call will be within the opening and closing tag. You will need to set either a var or a predicate around the callapi tag to be able to process the response.
response_code_var
This will be the http response code from the external service.
<callapi response_code_var="response_code">
<url>http://api.coindesk.com/v1/bpi/currentprice.json</url>
</callapi>
The url is the destination for the API call (aka endpoint). It can either be a service that you own and control (like your own server), or it can be a service that you are authorized to use (either a public service or one that you are registered for).
<callapi response_code_var="response_code">
<url>http://api.coindesk.com/v1/bpi/currentprice.json</url>
</callapi>
The method indicates the HTTP request method (e.g. GET , POST, PUT etc). This is optional, and if not specified within callapi, defaults to GET.
<callapi>
<url>[api-endpoint]</url>
<method>POST</method>
:
A header pair to be used in the HTTP request. Multiple header attributes can be used as needed. This is optional and only specified depending upon the API request requirements.
name
The name attribute for the header is specified by the API end point as a header parameter name. The header tag wraps around the value of the header parameter
<callapi>
<url>https://api.github.com/...</url>
<header><name>Authorization></name>token <secret name="github_token" /></header>
<header><name>User-Agent</name>freds_github_name</header>
</callapi>
The query parameter is where you would put items required by the API call. The variance can be because of how the API is structured or because you will be sending information generated by the user or your bot.
The queries will be built into the call based on the API method (e.g. appended to the URL). If method is identified as a POST or PUT, the query will be placed in the request’s body. Otherwise it will be placed in the URL
name
The name attribute for the query is the key for the query value. For example, if the query name was “foo” and the value “bar”, then the query would be appended as ?foo=bar.
<callapi response_code_var="tempcode">
<url>http://api.openweathermap.org/data/2.5/weather</url>
<query name="q"><star /></query>
<query name="APPID"><secret name="wkey" /></query>
<query name="mode">xml</query>
<query name="units">imperial</query>
</callapi>
Number of seconds that the Call API request should wait before specifying a timeout error. This is optional, with the default value being 10 seconds.
Additional AIML tags supporting the Call API feature
This tag retrieves secret credentials needed when calling an API endpoint. While you can hardcode credentials into your AIML files, or include them as bot properties, we do not receommend that. Using the <secret> tag hides your credentials that are stored encrypted on our backend system. This is handled the same as <bot> to retrieve values.
name
The name attribute for secret is the key in the secrets key/value pair.
<callapi response_code_var="tempcode">
<url>http://api.openweathermap.org/data/2.5/weather</url>
<query name="q"><star /></query>
<query name="APPID"><secret name="wkey" /></query>
<query name="mode">xml</query>
<query name="units">imperial</query>
</callapi>
Both XML and JSON are supported, and the responses are parsed using either xpath or jsonpath tags. Please review Xpath and JsonPath for details on the syntax for navigating nodes in an XML or Json response. This is useful to pick out specific information from an Call API result that you want to store as a variable or predicate for use in a bot response.
path
The path attribute for xpath or jsonpath is the path expression using standard syntax for parsing XML / JSON string.
<jsonpath>
<path>$.bpi.USD.rate</path>
<get var="response" />
</jsonpath>