HTTP vs. SMS

The HTTP vs. SMS flow template can be downloaded from the library and is a simple example of how to trigger an SMS to be sent over HTTP. In other words, it allows you to create an API endpoint that, when triggered, will send SMS messages to the phone number of your choosing.

Note: Testing this flow will be easier if you already have some basic API knowledge, specifically how to make a RESTful API call with a POST method in JSON format. You will also need an API client or some other way to make a POST request.

Getting Started

From your Bot Designer homepage, select an existing bot or create a new blank one. Once inside this bot, click the blue plus button to add a flow and select “Download from Library”.

Screen Shot 2018-04-18 at 1.46.10 PM

This will open up a window displaying the list of Library flow templates available for download.

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

Click the “Download” button beneath the flow labeled “HTTP vs. SMS”. You will see a notification bar at the top of the window; click on “Go to flow”.

Screen Shot 2018-04-18 at 1.49.17 PM

This will open up the flow in view-only mode. Click the “Edit” button at the lower right corner of the sidebar to enter edit mode and start configuring the flow.

Screen Shot 2018-04-18 at 1.51.49 PM

Next, we will go through each step in the flow and add any necessary configuration.

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 initiated. 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 also call this the Step UI. You will see two fields: Method, and Path.

Screen Shot 2018-04-18 at 1.57.09 PM

Method is the type of HTTP request this flow will expect to receive. Different methods have different functions. Just leave this field the way it is, which should be “POST”.

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 you cannot use 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 which 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 no longer missing any required data. Feel free to edit the text in the Message field; this is the content of the SMS 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 deployment URL.

Screen Shot 2018-04-18 at 2.13.26 PM

After anywhere from a few seconds to about a minute, you should 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, where we can get 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 URL 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.

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 (“merge field”) and splitting the flow logic based on that variable. This type of structure will prove useful when designing conversations, as it allows your bot to react dynamically based on user input, calculation results, API return data, etc.

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

Execute JavaScript code allows a flow designer to add custom JavaScript code to the flow logic. 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 and stored under the merge field you specify.

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

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 condition description accordingly.

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 curly braces {} 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 available for constructing 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 last field. Clicking it 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 if need be.)

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 our case, “x” cannot logically 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, which demonstrates one potential way of checking 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 try out the different Check Condition results.

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 whoever triggered it. We 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 source of the trigger 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