FOP2 IVR Flow module allows you to create interactive voice response systems (IVR) or other type of call flows and interactions using a simple drag and drop interface. It can interface with external APIs to gather data and select branches based on logic conditions, time conditions, selected options or spoken words via asterisk speech capabilities.

What you'll learn

What you'll need

In this tutorial we are going to query an external Rest API to get the Bitcoin price and announce it to the caller.

Log to the IVR Flow module via FOP2 Manager and create a new Flow via the Add button at the top. Fill the form like this and click Save:

Name: Bitcoin Price
Description: Query Web API to obtain and announce the Bitcoin price
Extension: 2101

Now open the canvas by clicking the Visual Editor icon:

illustration

Once on the canvas click on the Integrations category and drag the API Call block:

illustration

We are going to query the Coindesk API, so click on the API Call block on the canvas to set its properties and fill the following details:

Type: URL
Method: GET
URL: https://api.coindesk.com/v1/bpi/currentprice.json

When done click Save. We will see in the next step how to make sense of the returned data.

When you call the API endpoint URL in your browser you will get a result similar to this one:

{
  "time": {
    "updated": "Aug 25, 2021 18:20:00 UTC",
    "updatedISO": "2021-08-25T18:20:00+00:00",
    "updateduk": "Aug 25, 2021 at 19:20 BST"
  },
  "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": "48,917.7358",
      "description": "United States Dollar",
      "rate_float": 48917.7358
    },
    "GBP": {
      "code": "GBP",
      "symbol": "£",
      "rate": "35,571.3632",
      "description": "British Pound Sterling",
      "rate_float": 35571.3632
    },
    "EUR": {
      "code": "EUR",
      "symbol": "€",
      "rate": "41,598.4196",
      "description": "Euro",
      "rate_float": 41598.4196
    }
  }
}

IVR Flow will understand the JSON response and will flatten the data using dot separtor notation. It till also convert keys to uppercase and replace some special characters in key names like $ and : to an underscore.

It will also prepend key names with IVRFLOW_ to avoid potential collitions with standard Asterisk variables. If there is array data in a key, it will append the index number on each element also using dot notation to enumerate each value.

As we want to announce the Bitcoin price in USD, we want to get the value from IVRFLOW_BPI.USD.RATE_FLOAT (prepending IVRFLOW_ because its a Json result, then BPI, USD, RATE_FLOAT)

Now that we know what variable to use, we will just add a TTS Speech block at the end:

illustration

We will then click on the block to open the configuration window where we can fill the details:

Language: English
Text: Current Bitcoin Price is ${MATH(${IVRFLOW_BPI.USD.RATE_FLOAT}*1,int)} dollars.

Some explanation about the above needs to be done. When setting Asterisk commands you can use all of available Asterisk capabilites, like expressions, functions and variables. Variables in Asterisk use a dollar prefix and are enclosed in curly brackets. Like ${VARIABLE}.

You can also use functions. In this example we are making use of the MATH function just to round the number, as we do not care about announcing decimals.

We could have used the variable directly like _${IVRFLOWBPI.USD.RATE_FLOAT} but to show the potential usage and spice the things a bit we added an Asterisk function.

Congratulations! You now know how to query external APIs to get data you can use in your own logic and flows. You can dial 2101 and hopefully you will listen to the current Bitcoin price.

Further reading