Introducing Call API to Pandorabots

Pandorabots has added a new feature to AIML: Call API. This is an extension of the existing AIML 2.1 spec, but we are working on getting it standardized.

Call API was designed to solve two problems a lot of our bot developers had:

1. How do I get dynamic information, like the weather, into my bot?
2. How do I integrate my bot into my backend data system?

To solve these problems, you would previously have had to set up your own server running as a front end to your bot, passing through the user inputs and building AIML to pass back to your server, that it would then need to interpret to make an outside call (sometimes then passing information back through the bot before completing the round trip to the user).

Set up to integrate external service

With Call API, you can integrate those API calls, and the bots interpretation directly into your AIML. You can also send data from your bot directly to a service that you own.

Set up with Call API

Let’s look at a quick and simple outside temperature integration, and then we will build a call from scratch.

<category>
  <pattern>TEMP *</pattern>
  <template>
    <think>
      <set var="tempresp">
          <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>
        </set>
      </think>
    <condition var="tempcode">
      <li value="200"><get var="tempresp" /><xpath>/current/temperature/@value</xpath></li>
      <li><srai>TEMPFAIL</srai></li>
    </condition>
  </template>
</category>

If the user inputs TEMP Tempe, it would return the current outdoor temperature in Tempe, Arizona. You could also incorporate this into your conversation by responding with the temperature when you ask the user where they are from.

Building Call API from Scratch

Let’s build one from the ground up. We will use the CoinDesk bitcoin price API, since it’s open to the public without needing credentials, and the price is very dynamic, which makes updates easy to see.

The most basic Call API can be built into the template itself, like this:

<category>
  <pattern>WHAT IS THE PRICE OF BTC</pattern>
    <template>
        <callapi>
            <url>http://api.coindesk.com/v1/bpi/currentprice.json</url>
        </callapi>
    </template>
</category>

This will get is the full JSON package, which is the same as the JSON response from their endpoint here: https://api.coindesk.com/v1/bpi/currentprice.json.

{"time":{"updated":"Feb 18, 2020 05:25:00 UTC","updatedISO":"2020-02-18T05:25:00+00:00","updateduk":"Feb 18, 2020 at 05:25 GMT"},"disclaimer":"This data was produced from the CoinDesk Bitcoin Price Index (USD). Non-USD currency data converted using hourly conversion rate from openexchangerates.org","chartName":"Bitcoin","bpi":{"USD":{"code":"USD","symbol":"$","rate":"9,801.5000","description":"United States Dollar","rate_float":9801.5},"GBP":{"code":"GBP","symbol":"£","rate":"7,542.2248","description":"British Pound Sterling","rate_float":7542.2248},"EUR":{"code":"EUR","symbol":"€","rate":"9,050.0680","description":"Euro","rate_float":9050.068}}}

The information that we are interested in to start is the bitcoin price in USD. That is under bpi > USD > rate. To get there using jsonpath, we end up with $.bpi.USD.rate. You can use online tools, like JSON Pathfinder to help you parse your data. Let’s add that to make the response more sensible.

Note: if you are already running your own server in front of Pandorabots AIML interpreter, you can now pass full JSON into Pandorabots and parse using jsonpath.

Here’s the code:

<category>
  <pattern>WHAT IS THE PRICE OF BTC</pattern>
    <template>
        <jsonpath>
            <path>$.bpi.USD.rate</path>
        <callapi>
            <url>http://api.coindesk.com/v1/bpi/currentprice.json</url>
        </callapi>
        </jsonpath>
    </template>
</category>

And here’s the response:

10,238.1950

But, that doesn’t allow for any failure cases or debugging your responses. Let’s save our response in a var, which will allow us to do our processing once we know callapi worked.

Code:

<category>
  <pattern>WHAT IS THE PRICE OF BTC</pattern>
    <template>
        <think>
            <set var="response">
            <callapi><url>http://api.coindesk.com/v1/bpi/currentprice.json</url></callapi>
            </set>
        </think>
        <jsonpath>
            <path>$.bpi.USD.rate</path>
            <get var="response" />
        </jsonpath>
    </template>
</category>

Now that our response processing is set apart, we can add in conditionals to test callapi. We will capture the HTTP response code using response_code_var. On a value of 200, we want to parse the JSON path, but we want to respond that we couldn’t get the price if it responds with any other HTTP code. We can test various response codes by using https://httpstat.us/ as an endpoint URL, which allows for testing a lot of different response codes (though you will probably see some JSON path errors, if you’re trying to parse your original API endpoint url).

Code:

<category>
  <pattern>WHAT IS THE PRICE OF BTC</pattern>
    <template>
        <think>
            <set var="response">
                <callapi response_code_var="response_code">
                <url>http://api.coindesk.com/v1/bpi/currentprice.json</url></callapi>
            </set>
            <set var="content">
                <jsonpath>
                    <path>$.bpi.USD.rate</path>
                    <get var="response" />
                </jsonpath>
            </set>
        </think>
        <condition var="response_code">
            <li value="200"><get var="content" /></li>
            <li>Could not get the price.</li>
        </condition>
    </template>
</category>

Note: JSON path is case sensitive.

Now that you know some of the basics, you can build a bot with Call API on your own. We add some boilerplate to our code editor, so you can get started.

You don’t have to remember this off the top of your head

External Services and Secrets

This is all well and good for a public API, but some calls require authentications. We have you covered there. We have also introduced the concept of a secret file. This file is encrypted per bot, and it allows you to save and access API keys.

On your deploy page, there’s a new section called External Services/APIs.

You can create and update services, which will allow you to access your API secrets like you would any bot properties file.

Using Call API Builder

There are a lot of new concepts and tags with Call API, and the knowledge required extends beyond knowing AIML. To help using Call API, we added a builder, that will allow you to test your call, extract your path, and save the AIML to your bot.

Screenshot of Call API Builder

Call API is only available to users on the Developer and Pro plans. Sign up for Pandorabots and try it out today.