Messaging recipe: Getting external data for your messaging bot

Flow Builder’sMake API callstep lets a messaging bot use a REST API request to fetch data from an external system, such as Shopify or Salesforce.

In this recipe, you’lls create a bot answer that retrieves weather data for a location provided by an end user. The answer gets the data from theOpenWeather API. You can use the answer flow created in this recipe as a starting point for building your own API-powered answers.

The recipe involves the following tasks:

Note:Zendesk provides this article for instructional purposes only. Zendesk doesn't support the examples in this article. Zendesk also doesn’t support third-party technologies, such as the OpenWeather API.

Task 1: Checking your setup

To complete this recipe, you’ll need the following:

A Zendesk account with a published messaging bot. If you want, you can use asandbox testing environmentto test the bot before using it in production.
To set up a messaging bot on a web and mobile messaging channel, seeWorking with messaging bots for your web and mobile channels. To set up a messaging bot on a social channel, seeUsing Flow Builder to create a social messaging bot.For information about using messaging in a sandbox environment, seeUsing messaging in your sandbox.
An API key for anOpenWeatheraccount. The API used in this recipe is available on OpenWeather’s free plan.
To sign up for a free OpenWeather account, see the Create New Account page onopenweathermap.org. After signing in, you can get an API key on yourOpenWeather account page.
To activate OpenWeather API keys, you must verify your account email address. After verification, API keys can take up to two hours to activate. For more information, see the FAQ onopenweathermap.org.

Task 2: Creating an API connection

To start, create an API connection to store your OpenWeather API key. Your messaging bot can use this connection to authenticate calls to the OpenWeather API.

To create the connection

InAdmin Center, clickApps and integrationsin the sidebar, then selectConnections > Connections.
ClickCreate connection.
Select theAPI keyauthentication type.
Enteropenweather_api_keyas theConnection name.
Enterx-api-keyas theHeader name.
Enter your OpenWeather API key as theValue.
Enterapi.openweathermap.orgas theAllowed domain.
ClickSaveto create the connection.

Task 3: Creating a custom ticket field

Next, create a custom ticket field to capture the location provided by the end user.

To create the custom ticket field

InAdmin Center, clickObjects and rulesin the sidebar, then selectTickets > Fields.
ClickAdd field.
Select theTextfield type.
EnterLocationas theDisplay name.
UnderPermissions, selectCustomers can edit.
UnderCustomers, enterLocationas theTitle shown to customers.
ClickSave.

If your account uses a single ticket form, the new field automatically appears in your ticket form. To remove the field, seeEditing ticket forms.

Task 4: Building an answer using Flow Builder

This section walks you through creating the answer, setting its intent, and adding steps for the answer in Flow Builder. This involves the following steps:

Step 1: Creating the answer

Use Flow Builder to create an answer for your messaging bot.

To create the answer

InAdmin Center, clickChannelsin the sidebar, then selectMessaging and social > Messaging.
Hover over the bot you want to work with and clickEdit.
ClickCreate answer.

Step 2: Setting the answer’s intent

Set the answer’s intent and training phrases. These include phrases and words used to trigger the answer in a conversation.

To set the answer’s intent

On the Answers tab of the bot’s edit page, clickCreate answer.
EnterGet weatheras the answer’sIntent.
UnderTraining phrases, enterGet weather forecastandGet current temperature.
ClickNext.
The answer opens in Flow Builder where you can build out the bot’s response.

Step 3: Adding an initial message step

Add aSend messagestep to ask the user for a location. This is the first step in the answer’s flow.

To add an initial message step

In Flow Builder, clickAdd step.
UnderChoose step, selectSend message.

InBot message, enter the following text:

What location would you like to get the weather for? Include the country code. For example: "Melbourne, AU" or "San Francisco, US"

Step 4: Asking the end user for a location

After the initial message, add anAsk for detailsstep to present a basic form to the end user. The form includes a text box for theLocationticket field’s value.

To add an Ask for details step

In Flow Builder, click theAdd stepicon ().
UnderChoose step, selectAsk for details.
EnterGet locationas theName.
InFields, type and select theLocationticket field.

Step 5: Retrieving weather data for the location

Add aMake API call一步得到位置的天气数据OpenWeather API’sCurrent weather dataendpoint.

To add a Make API call step

In Flow Builder, clickAdd step.
UnderChoose step, selectMake API Call.
EnterGet weatheras theName.
UnderAPI details,enterhttps://api.openweathermap.org/data/2.5/weather?units=metric&q=as theEndpoint URL.
Use theAdd a variableicon () to append theLocationfield variable to theEndpoint URLvalue.
The finishedEndpoint URLvalue should look like this:
InAuthentication, select theopenweather_apiconnection.
To test the API request, clickMake API call.
UnderTest Data, enterMelbourne, AUas theLocation.
ClickMake API call.
Save the following variables using their default names:
- main>temp
- weather>item 1>description

Step 6: Sending a weather message to the end user

After retrieving the weather data, use aSend message一步反应d with a message containing the weather data.

To add an API success message

In Flow Builder, clickAdd stepunder theGet weatherstep’sAPI call successfulbranch.
UnderChoose step, selectSend message.

InBot message, enter the following text:

It's {{temp}}° C with {{description}} in

Use theAdd a variableicon () to append theLocationfield variable to theBot messagevalue. Then add a period (.).
The finishedBot messagevalue should look like this:

Step 7: Adding a failure message

The request made during theMake API callstep may fail. For example, the request may include a location that doesn’t exist. Add aSend messagestep to theAPI call failedbranch. This step returns a message if the OpenWeather API call fails.

To add an API failure message

In Flow Builder, clickAdd stepunder theGet weatherstep’sAPI call failedbranch.
UnderChoosestep, selectSend message.

In Bot message, enter the following text:

I'm sorry. I wasn't able to get weather data for

Use theAdd a variableicon () to append theLocationfield variable to theBot messagevalue. Then add a period (.).
The finishedBot messagevalue should look like this:

Step 8: Publishing your updated bot

To push the answer live, publish the updated bot.

To publish the bot

ClickDonein the upper right corner of Flow Builder.
On the bot page, clickPublish bot.
ClickPublish.

Task 5: Testing your changes

After you publish your changes, you can test the new answer by asking “How’s the weather?” in a conversation with the updated bot. For more information about testing messaging bots, seeTesting the end user's messaging experience.