HTTP Bot Sample

HTTP Bot Sample is a bot template available in the Library that demonstrates how to send an SMS with OneReach via an external HTTP trigger. In other words, it allows you to create an API endpoint that, when called, will send SMS messages to the phone number of your choosing.

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 “Find a Flight Bot,” wait for the confirmation, and hit “Go to bot.”

Screen Shot 2018-04-30 at 3.01.39 PM.png

Alternatively, you can close this 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-30 at 3.01.54 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-30 at 3.07.48 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-30 at 3.08.19 PM.png

Next, we will go through and configure each step in the flow. The instructions that follow are identical to the HTTP vs. SMS flow tutorial, so if you’ve already completed that you can either try doing the rest of this on your own or move on to other material.

HTTP Gateway

The first step in any flow must be a gateway step. This step creates the triggers that determine how and when the flow can be told to start executing. In this case, the step in use is Wait for Request (HTTP). This means it is an HTTP gateway, and this flow will be triggered via HTTP request. In other words, this step allows you to create an API endpoint.

Click on the Wait for Request (HTTP) step and the sidebar will show the step details. We call this the Step UI. You will see two fields: Method, and Path.

Screen Shot 2018-04-18 at 1.57.09 PM

The method is the type of HTTP request this flow will expect to receive. Different methods have different functions, but we won’t go into that here. Just leave this field the way it is, which should be “POST”.

The path is what will differentiate this HTTP-triggered flow from other HTTP-triggered flows in your OneReach account. No two HTTP-triggered flows can have the same path. Replace the “http” in this field with the unique path of your choosing; this will be appended to the end of the deployment URL once the flow is activated, so no spaces or special characters!. Here we have entered “http-sms-demo.”

Screen Shot 2018-04-18 at 2.00.49 PM

Ignore the “Advanced” and “Reporting events” dropdowns in the step UI for now, and move onto the next step.

Send first SMS

This step is highlighted in red, because there is a piece of configuration missing that is required for the step to function. Whenever you see a red step on your canvas, click on it and check the step UI to see what field is highlighted red.

In this case, the red field is “Bot phone number”. This is the number the SMS will be sent from. Click this dropdown and select one of your phone numbers from the list.

Screen Shot 2018-04-18 at 2.06.10 PM.png

In the “End user phone number” field, type your mobile phone number, or the number of the phone to which the text message should be sent. Make sure to use international format: “+”, then the country code, then your full phone number including area code. For US number (555) 222-3456, the international format would be “+15552223456”, since the country code for USA is 1.

Screen Shot 2018-04-18 at 2.08.56 PM

You’ll notice that the step has now turned blue, which means it is not missing any key data. Feel free to adjust the text in the “Message” field; this is the content of the text message that will be sent.

Screen Shot 2018-04-18 at 2.10.42 PM

First Activation and Test

At this point, with the first two steps configured, the flow is actually ready to be activated and tested. Click the down arrow on the right of the “Save” button and select “Save and Activate.” This will save the flow and activate its trigger(s), which in this case is the HTTP deployment URL.

Screen Shot 2018-04-18 at 2.13.26 PM

After anywhere from 10 seconds to a minute or so, you will see a notification at the bottom of the sidebar informing you of the successful activation.

Screen Shot 2018-04-18 at 2.20.35 PM

Now click the “Back” button to exit edit mode; this will allow us to see the deployment details and copy the URL that is our new endpoint.

Once back in view-only mode, click the “Deployment” tab in the sidebar. You will see trigger information including the type of trigger (HTTP) and the method (POST), as well as a button to copy the deployment URL. Click this button and the endpoint will be copied to your clipboard.

Screen Shot 2018-04-18 at 2.21.55 PM

Trigger the Flow

To test this flow, it will be helpful to have at least a basic understanding of how to make API calls.

Now you will need to open up your API client or whatever kind of API testing tool you will use. (This would be a piece of software, web app, etc. that allows you to make custom API calls. Postman is one such example.) The screenshots that follow were taken in Postman.

In the URI/URL/endpoint field, paste the URL you copied from your flow, and select “POST” as your method.

Screen Shot 2018-04-18 at 2.29.58 PM

Since we didn’t add any authentication checks to this flow, you will not need any authorization headers. However, you will need to specify that it is a JSON request with a “Content-Type” header:

Content-Type = application/json

If you are using Postman, you can specify JSON (and automatically add the content-type header) by navigating to the Body tab, selecting “raw”, and choosing JSON (application/json) from the dropdown.

Screen Shot 2018-04-18 at 2.34.08 PM

Now, you can make the call! If you’re in Postman, click “Send.”

Within a few seconds, you should receive a successful 200 OK response, and the text message should arrive on your phone.

Screen Shot 2018-04-18 at 2.39.24 PM

Screen Shot 2018-04-18 at 2.41.01 PM

If this worked, stop and congratulate yourself! You’ve successfully used HTTP to send an SMS using Communication Studio.

The rest of the flow introduces the concept of setting a variable and splitting the flow logic based on that variable. This type of structure will prove useful when designing conversations, as it allows you to tell your bot to react dynamically based on user input or calculation results.

Setting a Variable

Open up your flow and get back into edit mode. Click on the Execute JavaScript code step. You’ll see two fields: Code, and Merge field.

Screen Shot 2018-04-18 at 3.48.51 PM

This step allows a flow designer to insert any custom JavaScript code they wish. If you don’t know JavaScript, don’t worry – you can build fully functional flows without using this step at all! Here, though, we are demonstrating how you can use Execute JavaScript code to create a new merge field or reassign the value of an existing merge field.

In the Code box, there is one line of text:

return 1;

All you need to know is that whatever comes after “return” will be set as the output of this step. That is, whatever you “return” in the code box will be stored in the merge field you set below.

In this case, we are creating a merge field “x” whose value will be 1. You can change this value by replacing the 1 with another number, or even replace it with text (surrounded by single or double quotes) to set a text value. For now, leave it as 1.

Split Flow Logic Based on Merge Field

Now that we have created a merge field “x”, we can use a Check Condition step to create different branches of flow logic based on the value of “x.”

Click on the step and you will see two existing conditions in the step UI, as well as three exit branches on the canvas.

Screen Shot 2018-04-18 at 4.06.16 PM

There are three branches because the Check Condition step automatically creates an “else” branch to handle any result not matching the conditions created in the step UI.

Let’s take a look at the first condition. Hover your mouse over the “one” condition in the step UI and click the pencil icon that appears to the right.

Screen Shot 2018-04-18 at 4.10.08 PM

This will open the Edit Condition window, where you can see the details and rules of this condition.

Screen Shot 2018-04-18 at 4.11.23 PM

As the description states, this condition will be met (and the corresponding branch followed) if the merge field “x” is equal to 1. This was achieved by creating a rule. Let’s create our own additional rule to see how it’s done; we’ll add a check to see if “x” is equal to 0, and adjust the description to include this additional rule.

First, click “Add rule” beneath the existing rule. You’ll see another line appear:

Screen Shot 2018-04-18 at 4.16.19 PM.png

Click inside the {} on the left to bring up the list of existing merge fields, and select “x.” This is the value we will be checking.

Screen Shot 2018-04-18 at 4.18.01 PM

In the comparison dropdown, select “is.” You’ll notice a host of other comparison operators you can use to build more complex conditions.

Screen Shot 2018-04-18 at 4.20.24 PM

Finally, in the rightmost field, type the number “0.”

Screen Shot 2018-04-18 at 4.21.39 PM

(Notice the merge field Screen Shot 2018-04-17 at 12.06.27 PM button above this rightmost field. Clicking this will bring up your list of existing merge fields; this means it is possible for you to compare the value of one merge field to another, and thus create dynamic conditions.)

The any/all setting is already set to “any”, which means this condition will match if “x” is equal to 1 or to 0. If you change this to “all”, every rule in the list would have to be true for the condition to match. In this case, “x” cannot be equal to 0 and 1 at the same time, so if we used “all” this condition would never match.

Now, we have to make sure we can tell what this condition is looking for without opening up the Edit Condition window. We’ll just add some clarity to the label and the description:

Screen Shot 2018-04-18 at 4.30.19 PM

Click Save, and the window will close. Notice that the first condition in the list has changed to match our new label and description.

Screen Shot 2018-04-18 at 4.31.31 PM

Now, if “x” is equal to 1 or 0, this step will exit via the “one/zero” leg.

Let’s move on to the second condition. This condition demonstrates how you could use the Check Condition step to split your flow logic based on user input. (You don’t actually have to make any changes here, but it’s worth looking at.)

Click the pencil icon next to the “no” condition to open up the Edit Condition window. You’ll see one rule, matching some merge field “yes” to either “no”, “n”, or “nope”. Of course we haven’t created a “yes” merge field anywhere else in the flow, but this is just demonstrating possible ways to match user responses in a conversational flow. Feel free to replace “yes” with our merge field “x” and add any other rules you’d like to play around with. Then, when you’re testing your flow, you can change the value of “x” in the JavaScript step to experience the different branches.

Add Messaging to Branches

Beneath each branch of the Check Condition step, there is another SMS step. Feel free to change the messaging within each of these steps to whatever you like. Notice how you can use merge fields to dynamically insert data into the SMS message text. Don’t forget to fill in the end user phone number so the system will know where to send the SMS!

Screen Shot 2018-04-18 at 5.10.56 PM

Send HTTP Response

To complete this flow, we must send a response back to the source of the initial trigger. We can use the Send Response (HTTP) step to do this. Here, each of these Send Response steps is sending back a 200 OK, which tells the triggering entity that the API call was a success. Messaging is included which provides more details on the successful response, and you can customize that if you wish, but no messaging is necessary for the 200 OK to be sent.

Screen Shot 2018-04-18 at 5.16.09 PM

If you were building a more complex API, you could use this Send Response (HTTP) step to send back specific error responses as well. You can see the available error codes in the “Status code” dropdown.

Finish Up

The Send Response (HTTP) step will always be the last step in an HTTP-triggered flow, as you can see by the lack of exit branch. Go ahead and save and activate the flow to test the additional steps we just configured. If you’d like to test the different Check Condition branches, change the value of “x”, then save and activate again before triggering.

 

Great job!

 

 

 

 

 

 

 

Advertisements