Weather ITR

Weather ITR is a bot template available in the Library that demonstrates a sample SMS architecture. Use this template to build a responsive SMS bot that users can text into to get tailored information.

Getting Started: Download Bot

After logging into Communication Studio, you’ll be taken to the Bot Designer homepage, where all your bots (if you’ve created any) are listed. Click the blue plus button in the lower right corner, then select “Download from Library.”

Screen Shot 2018-04-26 at 12.14.17 PM

A window will open showing the available bot templates. Click the Download button beneath “Weather ITR,” wait for the confirmation, and hit “Go to bot.”

Screen Shot 2018-04-26 at 12.34.21 PM.png

Alternatively, you can close the window and open the new bot from your Designer homepage.

Edit your flow

The sample use case demonstrated in this template is fairly simple, so there is only one flow in the bot.

Screen Shot 2018-04-26 at 12.37.52 PM.png

Click on this flow to open it up in view-only mode. Now you can see the tree of steps that make up the flow logic.

Screen Shot 2018-04-26 at 12.38.51 PM.png

Click the Edit button in the lower right corner to open the flow in edit mode and start configuring the steps.

Screen Shot 2018-04-26 at 12.40.03 PM

Next, we will go through and configure each step in the flow. The instructions that follow are identical to the “Get weather in your location” flow tutorial, so if you’ve already completed that, you can stop here.


As you may already know, every flow in the Designer must have some sort of gateway as its first step. The gateway step determines how and when the flow can be triggered to begin its execution, as well as setting up any necessary flow configuration for the channel in question. In this case, we are creating a flow that will be triggered by an incoming text message, so the gateway step in use is Wait for message (SMS). This will create an SMS listener on the bot phone number, so an SMS sent to that number will initiate the flow.

Click on the Wait for message (SMS) step, which, again, is the first step in the flow. The step is highlighted in red because it is missing some required configuration. In the sidebar on the left, you can see the step details, where the Bot phone number field is highlighted in red. This tells you that the bot phone number is required for the step to function properly.

Screen Shot 2018-04-19 at 2.24.50 PM

Click the Bot phone number dropdown and select a number from the list. The step will now turn blue, indicating that the missing configuration has been provided.

Screen Shot 2018-04-19 at 2.26.11 PM.png

The next field in the step UI, End user phone number, has been left blank, because we want this flow to respond to anyone who might text in. Remember, this step is setting up our flow trigger(s). If you specify a phone number in this field, the flow will only initiate if it receives an incoming SMS from that phone number.  (For example, you might use this if you wanted a flow to only respond to a certain group of VIP customers.)

The final field, Keyword or phrase, allows you to constrain the flow to only kick off if the text of an incoming SMS matches a certain text value. This can prove useful if you want to have multiple flows listening on the same bot phone number, since two flows with the same trigger can’t logically coexist. (For example, you may have multiple tasks a user can perform by texting your business, and the different tasks are triggered by different keywords.)

In this case, the keyword required to initiate this flow is “weather”. You can change this if you wish, but we will leave it as-is for now. (Note that the keyword is not case-sensitive.)

At this point, if you haven’t saved any of your changes yet, click the Save button to do so. It’s a good idea to do this periodically.


Now that the gateway has been configured, we can start looking at the way the flow will interact with the end user. The first step is to respond to their incoming message and let them know what the bot is capable of.

Click on the “Welcome Message” step, which uses the Send Message (SMS) step template. This step template allows you to send an SMS to the end user, then immediately proceed to the next step in the flow (without waiting for a response). Here, we are greeting the user with “Hi! This flow can help you to get weather forecast in your area.” Feel free to adjust the content of this message if you wish!

Screen Shot 2018-04-19 at 3.14.18 PM

Notice that, since we set the bot phone number in our gateway, it has trickled down into this step and we don’t have to manually select it. The same will hold true for any other SMS steps in this flow, saving us time.

The End user phone number field is already configured with a merge field. In order to send this SMS to the person who initiated the flow, we use the merge field {incomingSMS} that the SMS gateway automatically creates. This merge field is a single JSON object that stores the end user number, bot number, and initial incoming message content.


In order to provide the user with local weather data, we must obtain their location. In this flow, the API we are using to retrieve weather data requires only the name of the city.

Since we want to capture user input via SMS, the step we need is Request text input (SMS). This step differs from the Send message (SMS) step in a major way: instead of sending the SMS and immediately moving on to the next step in the flow, the Request text input (SMS) step waits and listens for a text message response from the user before proceeding to the next step. It also stores the user’s response in a merge field so the content of their message can be used in the flow.

Here, we are simply asking the user for their location, clarifying the specific data we need: “Please, enter your location (city name).” You can change this if you like.

Screen Shot 2018-04-19 at 3.28.53 PM

Notice the Merge field field. This is where the user’s response to this message will be stored. Here we are using “city”, since the user is expected to respond with that specific piece of data.

Click the Advanced dropdown beneath Merge field. Here you can see the bot phone number and end user phone number, which should match the previous steps.

Screen Shot 2018-04-19 at 3.32.52 PM


Sometimes, when your flow needs to make an API call during a conversation, it can be a good idea to notify the user of the task in progress, in case the API call takes a little while. (Having a clearer understanding of the reason for a wait can improve customer satisfaction.)

Here, we are confirming the user’s choice of city and informing them of the potential delay while we fetch their local weather data. Notice the use of the {city} merge field we created in the previous step; inserting the merge field into the message text allows us to respond dynamically to the user with their choice of city.

Screen Shot 2018-04-19 at 3.38.35 PM

Again, feel free to edit this message as you see fit.


Now that we have the user’s location, we can make an API call to a weather service to retrieve the local weather data.

Click on the Make API request step. This useful step allows you to make an external HTTP request to any RESTful API endpoint and is completely customizable. Here, we are making a GET request to the free OpenWeatherMap API. In the URL field, we have the OpenWeatherMap endpoint, and “GET” is selected in the Request method dropdown.

Screen Shot 2018-04-19 at 3.44.53 PM

So far, this is a generic request to the endpoint, but we need to use {city} to specify the location. Click Query string parameters to expand that section of the step UI and scroll down.

Screen Shot 2018-04-19 at 3.47.03 PM

Here we have three query string parameters that have been created. The first, “q”, represents the query we are sending, and as such this is where we use the {city} merge field to dynamically query based on the end user’s input.

Screen Shot 2018-04-19 at 3.50.04 PM

The next parameter, “APPID”, is specific to this API and to the OneReach account we hold with OpenWeatherMap. You can ignore this.

The final parameter, “units”, allows you to specify metric or imperial format for the returned data. It is currently set to “metric”, but if you prefer Fahrenheit to Celsius, replace this with “imperial”. (Advanced option: If you want to add additional functionality to this flow, try asking the user which format they prefer, and use a merge field here to set their preference.)

Screen Shot 2018-04-19 at 3.56.40 PM

We don’t need to change anything else about this step’s configuration, but we will go through the other sections for educational purposes. If you’re already familiar with the Make API request step, or if you’re in a hurry to get your flow working, feel free to skip to the next section of this tutorial.

Close the Query string parameters section and click on Headers. There is nothing currently here, but if you were using an API that required authentication, you would likely need to insert auth information using headers.

Close Headers and open Advanced. This section allows you to set a custom timeout (how long you would like to wait for a response before declaring the API call a failure), a merge field name where the API response will be stored, and the expected format of the response.

Here, the merge field is set to “weather”. This merge field will store the complete body of the API response.

Here’s where it gets a little more complicated. Take a look at the Response Example box, and scroll through its contents. This all-important field makes it much easier to use the results of your API call later in your flow by structuring the output merge field to contain the nested parameters found in the response body. Filling in this field is a simple matter of copy-pasting the body of a response from the API endpoint in question.

In this case, the OpenWeatherMap API returns a lot of data, which we will need to parse in order to display to the user. The data is structured as a JSON object with various parameters, all of which will be stored under that {weather} merge field. If, for example, we wanted to access the “humidity” parameter in a later step, we would express the merge field as {weather.main.humidity}. (Dot notation is a common way of expressing nested data.) Since Response Example has been configured, the merge field list will suggest the proper dot notation to get at the various pieces of data in {weather}, instead of leaving you to figure it out yourself. If Request Example were left blank, the following screenshot would just show “weather” instead of this nice list:

Screen Shot 2018-04-19 at 4.35.56 PM

Save yourself from extra typing, and make use of Request Example in your API calls!


Now that we’ve made our API call, we can get back to our end user with the result.

Notice how the Make API request step has three exit branches. These branches allow you to take different actions depending on how the API call goes. If the API call is successful, the step will exit via the “success” branch. If an error code is returned, the “error” branch will be taken. Otherwise, if the request doesn’t get a response within the timeout time, the “timeout” branch will be taken. It’s best practice to always account for possible errors and keep your end users informed. Here, we are sending the end user a different message for each different result.

Screen Shot 2018-04-19 at 4.42.52 PM

First, let’s take a look at the “success” branch. Click on the Send message (SMS) step. This is what we will send to the user if the API call was a success.

Screen Shot 2018-04-19 at 4.48.51 PM.png

See how the merge fields use dot notation to express the specific pieces of data? Feel free to adjust this message to your liking; you can even click the {x} to get the list of available merge fields and insert additional weather info.

Again, the bot phone number and end user phone number have trickled down, so we can leave those as-is.


If our API call fails or times out, we need to tell the user something went wrong (instead of leaving them hanging). Click on the step under the “error” leg:

Screen Shot 2018-04-19 at 4.53.15 PM.png

This is a generic error message. You can change it however you wish.

Finally, the step under the “timeout” leg contains another generic message, this time specifying the timeout. It’s up to you if you want to be that specific with your users, but the differentiation can be helpful for your own troubleshooting. However, it’s totally acceptable to use the same error message for both the “error” and “timeout” legs.

Screen Shot 2018-04-19 at 4.55.13 PM


All set! Your flow is configured and ready to go. To save and activate, click the arrow next to the “Save Flow” button and select “Save and Activate.” This will save your changes, then check the flow for errors and activate the SMS gateway.

Screen Shot 2018-04-17 at 1.40.15 PM

After anywhere from 5 seconds to a minute or so, you’ll see a notification that the activation was successful.

Screen Shot 2018-04-17 at 1.34.20 PM

Now, you can test your flow! Send an SMS with the keyword to the bot number to get started.


Once you’ve run through your flow once or twice, exit edit mode and click on the Deployment tab in the sidebar. In the traffic dropdown, you will see options for loading traffic for various periods of time. The default is one hour; you can leave this as-is. Click “Show traffic” and a visualization of your path(s) through the flow will appear on the canvas:

Screen Shot 2018-04-19 at 5.02.53 PM.png