Build a simple weather voicebot with Proximus FlexIO

In this tutorial we will learn how to use the Proximus FlexIO Visual Designer to make queries to external systems. By reserving a phone number on the platform, we can implement a simple voicebot that will give the weather forecast to the caller for any Belgian region.

Integrating with external systems is typically done via API (Application Programming Interface). This tutorial doesn’t require code development skills, but introduces data manipulation. Less experienced users may wish to start with simpler tutorials first.

Book a new number

Once logged on API Solutions, open a new browser tab to the Proximus FlexIO Number Management microsite and register a new phone number to your account.

Create the FlexIO Visual Designer application

Creating the blank application

Go to the “Applications” section of the Proximus FlexIO console, and click on the “+ Add New App” button, then “Create a Visual Designer Application”. Select the “Blank” template in the Template Gallery.

Give your application a new name and make sure the type “voice” is selected before clicking on “Create”.

The Visual Designer window opens in a new tab. We can see several components in this window:

• Building blocks on the left: these are all action types that you can execute in your scenario, like “Play” for playing an audio file, “Say” to use text to speech, “Collect” to gather input from the caller, etc
• These action blocks can be dragged in the main screen, one below the other. They can be reordered on the screen and will be executed in sequence.
• Modules can be created and are ways to regroup action blocks together. There is always a startup module that will execute first. When creating a new application, the default module is called “Welcome”. Modules can be linked together using specific actions in some building blocks.

Configuring the modules

When people will call your weather voicebot we will need 3 modules to support the application:

• a welcome module will greet the callers with a welcome message and ask them for the postal code of the city for which they want a weather forecast
• a second module, let’s call it “datafetch” will use an external weather provider to retrieve the forecast
• a third module, “sayweather” will share the forecast with the caller than will hang up the phone

Let’s prepare the ground and create the needed empty modules:

Collecting the user input

We go back to our welcome menu, delete the unnecessary “Say” action and drag a “Collect” action from our building block palette. Within the Collect action we will drag a Say action and fill it in with our invite message : “Welcome to your personal weather voicebot. Please type in the 4 digits of your city’s postal code”. Don’t forget to use the settings of the Say action to choose the right text to speech engine and voice type:

We need to continue configuring the Collect action by:

• specifying you want to collect digits – and not run a menu
• state that we want to collect 4 digits, not less, not more
• assign the collected digits to a variable that we will call “postalcode” that should be available everywhere in the application, and not only in this very specific module
• branch to the module “datafetch” once the input is collected

We have left many possible options on the side for now in this Collect action, but you can see this single action can be rather complex, allowing to handle error conditions, to collect user input by speech to text instead of digits, etc.

Fetch and extract the weather data

We will to OpenWeather Map service to query our data. We need first to create an account on that platform. Go to Open Weather Map sign up page and sign up for an account. Once your account is validated, we will receive a mail that contains your API key to use with this service, so we save that email. In case we loose the email, we can find the API key again by going to https://home.openweathermap.org/api_keys

To fetch the data, we will need to address our queries to the following API URL:

http://api.openweathermap.org/data/2.5/weather?zip=$postalCode,be

We go to our “fetchdata” module in the Visual Designer, and add the action “External Service”, then configure it with the API URL above and 2 service parameters: “appid” with the value of our API key and “units” to specify we work with “metric”units:

When the OpenWeather Map service is called with these parameters, it will answer with a data structure, in a format called “json”. Here is an example of a typical output:

{
    "coord": {
        "lon": 4.38,
        "lat": 50.85
    },
    "weather": [
        {
            "id": 803,
            "main": "Clouds",
            "description": "broken clouds",
            "icon": "04d"
        }
    ],
    "base": "stations",
    "main": {
        "temp": 24.18,
        "feels_like": 22.48,
        "temp_min": 23,
        "temp_max": 25,
        "pressure": 1018,
        "humidity": 38
    },
    "visibility": 10000,
    "wind": {
        "speed": 2.1,
        "deg": 0
    },
    "clouds": {
        "all": 64
    },
    "dt": 1595504099,
    "sys": {
        "type": 1,
        "id": 1227,
        "country": "BE",
        "sunrise": 1595476584,
        "sunset": 1595533272
    },
    "timezone": 7200,
    "id": 0,
    "name": "Bruxelles Schaarbeek",
    "cod": 200
}

From this data structure, we will want to extract 2 elements:

• The temperature, “temp”, which is under the element “main”
• The weather description, “description”, which is under the element “weather”. That “weather” element is an array that could hold multiple weather descriptors

Let us first assign the temperature (“temp”) to a variable called “temperature” that we want to be accessible to the whole application, not only to the current module. Pay caution to the way we specify how we reach this value in the data structure:

Now let us take the same approach to get the value of the object called description located at the array index 0 contained in the object called weather:

Finally, we tell the External Service action to jump to our module “sayweather” once the data extraction is done and the values assigned to our variables. Note again that this action block can be much more configured in order to deal with error conditions and dynamic branching based on the content of the variables, but we will leave this aside for this tutorial:

Telling the weather to the caller

For this final step, we go to our sayweather module and add a simple Say action. The text we paste in this action is shown below, where use the variables weather and temperature that we created in the former step:

The weather today will be $weather with an expected temperature of $temperature degrees. Thank you for using our services. Goodbye now.

And finally add a Hangup action to close the call.

Do not forget to save your application before closing the Visual Designer.

Link your FlexIO phone number to the application

The final step is to tell Proximus FlexIO that it needs to trigger this new application once the platform receives a call for your number. To do so, we go back to the FlexIO Console and select the “Numbers” section to find our newly reserved number and click on it. From the drop down list next to “Voice request”, we select our application then click on “save changes”:

Give it a try ! Now is a good time to call your number to test that everything is working well.