Messaging recipe: Getting external data for your messaging bot

Flow Builder’s Make API call step 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’ll create a bot answer that retrieves weather data for a location provided by an end user. The answer gets the data from the OpenWeather 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:

• Task 1: Checking your setup
• Task 2: Creating an API connection
• Task 3: Creating a custom ticket field
• Task 4: Building an answer using Flow Builder
• Task 5: Testing your changes

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 a sandbox testing environment to test the bot before using it in production.

  To set up a messaging bot on a web and mobile messaging channel, see Working with messaging bots for your web and mobile channels. To set up a messaging bot on a social channel, see Using Flow Builder to create a social messaging bot. For information about using messaging in a sandbox environment, see Using messaging in your sandbox.

• An API key for an OpenWeather account. 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 on openweathermap.org. After signing in, you can get an API key on your OpenWeather 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 on openweathermap.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

1. In Admin Center, click Apps and integrations in the sidebar, then select Connections > Connections.
2. Click Create connection.
3. Select the API key authentication type.
4. Enter openweather_api_key as the Connection name.
5. Enter x-api-key as the Header name.
6. Enter your OpenWeather API key as the Value.
7. Enter api.openweathermap.org as the Allowed domain.
8. Click Save to 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

1. In Admin Center, click Objects and rules in the sidebar, then select Tickets > Fields.
2. Click Add field.
3. Select the Text field type.

   

4. Enter Location as the Display name.
5. Under Permissions, select Customers can edit.
6. Under Customers, enter Location as the Title shown to customers.
7. Click Save.

If your account uses a single ticket form, the new field automatically appears in your ticket form. To remove the field, see Editing 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
• Step 2: Setting the answer’s intent
• Step 3: Adding an initial message step
• Step 4: Asking the end user for a location
• Step 5: Retrieving weather data for the location
• Step 6: Sending a weather message to the end user
• Step 7: Adding a failure message
• Step 8: Publishing your updated bot

Step 1: Creating the answer

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

To create the answer

1. In Admin Center, click Channels in the sidebar, then select Bots and automations > Bots.
2. Hover over the bot you want to work with and click Edit.
3. Click Create 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

1. On the Answers tab of the bot’s edit page, click Create answer.
2. Enter Get weather as the answer’s Intent.
3. Under Training phrases, enter Get weather forecast and Get current temperature.
4. Click Next.

   The answer opens in Flow Builder where you can build out the bot’s response.

Step 3: Adding an initial message step

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

To add an initial message step

1. In Flow Builder, click Add step.
2. Under Choose step, select Send message.
3. In Bot 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 an Ask for details step to present a basic form to the end user. The form includes a text box for the Location ticket field’s value.

To add an Ask for details step

1. In Flow Builder, click the Add step icon ().
2. Under Choose step, select Ask for details.
3. Enter Get location as the Name.
4. In Fields, type and select the Location ticket field.

Step 5: Retrieving weather data for the location

Add a Make API call step to get weather data for the location from the OpenWeather API’s Current weather data endpoint.

To add a Make API call step

1. In Flow Builder, click Add step.
2. Under Choose step, select Make API Call.
3. Enter Get weather as the Name.
4. Under API details, enter https://api.openweathermap.org/data/2.5/weather?units=metric&q= as the Endpoint URL.
5. Use the Add a variable icon () to append the Location field variable to the Endpoint URL value.

   The finished Endpoint URL value should look like this:

   

6. In Authentication, select the openweather_api connection.
7. To test the API request, click Make API call.
8. Under Test Data, enter Melbourne, AU as the Location.
9. Click Make API call.
10. 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 a Send message step to respond with a message containing the weather data.

To add an API success message

1. In Flow Builder, click Add step under the Get weather step’s API call successful branch.
2. Under Choose step, select Send message.
3. In Bot message, enter the following text:

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

4. Use the Add a variable icon () to append the Location field variable to the Bot messagevalue. Then add a period (.).

   The finished Bot messagevalue should look like this:

   

Step 7: Adding a failure message

The request made during the Make API call step may fail. For example, the request may include a location that doesn’t exist. Add a Send message step to the API call failed branch. This step returns a message if the OpenWeather API call fails.

To add an API failure message

1. In Flow Builder, click Add step under the Get weather step’s API call failed branch.
2. Under Choose step, select Send message.
3. In Bot message, enter the following text:

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

4. Use the Add a variable icon () to append the Location field variable to the Bot messagevalue. Then add a period (.).

   The finished Bot messagevalue should look like this:

   

Step 8: Publishing your updated bot

To push the answer live, publish the updated bot.

To publish the bot

1. Click Done in the upper right corner of Flow Builder.
2. On the bot page, click Publish bot.
3. Click Publish.

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, see Testing the end user's messaging experience.