Use the SMS Module

A guided tutorial in our "How-to" series

Introduction

Added in Fuse 7.5, the SMS module allows you to add outbound SMS messaging to your Fuse application. Use cases for outbound SMS messaging are numerous, including two-factor authentication, customer order confirmations, and more.

In the following tutorial, you will build a basic Fuse application that uses the SMS module to send an outbound SMS message.

Prerequisites

• An active Plum Fuse account with at least one (1) phone number for deployment purposes.

• Some familiarity with Fuse's interface. Read our Fuse Basics tutorial to get started.

• An active Plum DEV* account with at least one (1) SMS-enabled, non-PCI number.

• A testing device or application with a phone number that can receive SMS messages. A mobile phone, a smart phone, Google Voice, or anything else similarly SMS-enabled should work.

• Read our docs on the SMS module.

How many phone numbers is that? To review, you'll need a total of three (3) phone numbers: 1) one for deployments in your Fuse account, 2) one that's SMS-enabled and non-PCI in your DEV account, and 3) one more for your SMS-capable device or application for testing purposes.

When you are ready to begin, log in to your Fuse account.

*Why is a DEV account needed, too?

In Fuse's current version (7.5), the SMS module is tied to DEV's SMS REST API. The module sends messages from an SMS-enabled, non-PCI number on your DEV account.

Step 1: Create a new application

First, you'll create a new application to use the SMS module.

In the Application Manager, select New Application .

Figure 1: Creating the application.

Enter an application name. If needed, you can also select a different default language.

When finished, select Create . Your new application will be opened in the Application Editor.

Step 2: Build the application

Next, you'll set up your application's call flow, which will include the SMS module.

IMPORTANT: Remember to save often when editing an application!

In the Application Editor workspace, add a Prompt module, and change the default module name.

Enter a brief welcome message to callers, and connect the Start module to the Prompt module, as shown below.

Figure 2: Adding a welcome message to callers.

Next, add an SMS module. Change the default module name, and connect your Prompt module to the SMS module.

Enter your Plum DEV account credentials, then select Authenticate as shown below. On success, the SMS module will connect to your Plum DEV account and display new fields.

Figure 3: Entering Plum DEV credentials in the SMS module.

In the SMS Phone Number dropdown box, select one of your available SMS numbers.

In the Recipient Phone Number field, enter the phone number* for your SMS-enabled test device and your message in their respective fields as shown below.

Figure 4: Entering the recipient number and a message.

*NOTE: As shown in Figure 4, you can enter a ten-digit long code phone number without any formatting symbols.

The phone number field accepts multiple number formats as well as variables, if you choose to set them. For more details on accepted phone number formats, see the table of phone number formats here.

OPTIONAL (Click to expand): What if you don't have a number, or know who might call?

Instead of a number, you could enter a shadow variable – a global session variable in Fuse – to return a caller's phone number as your recipient.

Steps

In the SMS module's Recipient Phone Number field, select the Add Variable icon.

Enter session.connection.ani into the Variable Name field in the Add Variable window. Select Add to add this new variable to the module's Recipient Phone Number field.

When the application reaches this module during a call, your SMS message will be sent to the number returned by the session.connection.ani shadow variable.

You can proceed with the remaining tutorial steps from here.

Why this works

Shadow variables are global session variables available in any Fuse application that can return info about a call as it happens. The session.connection.ani shadow variable contains a caller's phone number. You can also use session.connection.dnis.

Shadow variables can be useful in scenarios like this one where you may need to collect and use in-call information that isn't available to you beforehand. For more info on shadow variables, see Additional reading and resources.

The SMS module is now ready for use.

Next, add another Prompt module, change the default name, and connect the SMS module to it. Add a brief closing message that also explains to callers what the application has done. See the following image for an example.

Figure 5: Adding a closing message to callers.

Finally, add an Exit module, and connect the previous Prompt module to it.

Your application's call flow is now complete. The following image gives an example of what it may look like.

Figure 6: The completed application.

NOTE: If you followed the optional step above for the SMS module (under Figure 4), your recipient field will contain a variable instead of a phone number.

Select Save to save your application changes, then select the Exit icon to return to Fuse's Application Manager.

Step 3: Deploy and test your application

Finally, you'll deploy your application and do a test call to see if it performs as intended. You'll also check the call log for your test call for any issues.

Deployment

From the Application Manager, go to Deployments at the top of the page.

Select Add Deployment .

Figure 7: Setting up a new deployment for your SMS application.

Complete the following fields in the Add New Deployment window:

1. Deployment Label: Enter a unique name for this deployment.

2. Select Application: Select the name of your application from the dropdown box.

3. Select Revision: Select the version of your application that you want to deploy. Leaving this on latest is fine if you want to always use the most recent version of your application.

4. Deploy to: Select the phone number that callers will dial to reach your deployed application. This is the phone number associated with your Fuse account.

When you are finished, select Deploy to deploy your application. The new deployment will also be added to the Deployments table.

Your application is now active and ready to receive calls. You can test your application by calling the phone number you set for its deployment.

Testing

Dial your deployment's phone number using your SMS-enabled testing device or application. Once connected, your application should perform all of the interactions built in by you, including sending an SMS to your test device's number.

If you built the same application as shown in this tutorial, you should

1. Hear the message in the welcome prompt

2. Receive an SMS message on your test device/application, and

3. Hear the message in the closing prompt before the call ends.

Once your test call has ended, you can review the call log to see a detailed record of your application's behavior.

Review your call log

In Fuse, select Logs at the top of the page. In the Logs page, locate the session log for your test call in the table, then select the View Logs icon, as shown below.

Figure 8: Opening a detailed log for a call.

The Call Log page will be displayed with a detailed log of your test call. You can review each interaction of the call line-by-line to check whether or not your application worked as you intended, as shown below.

Figure 9: Viewing a detailed call log.

Your test call log should contain SMS-related entries. Select the plus icon next in the log entry that reads "SMS Request Queued". The log entry will expand to show more details on your SMS message, as shown below.

Figure 10: Viewing a log entry for SMS messaging.

If your message was sent successfully, this log will display your SMS-enabled phone number from DEV, your recipient's number, and your message.

See the following troubleshooting tips if your application runs into issues. Otherwise, you've completed this tutorial!

Troubleshooting tips (Click to expand)

What if my app isn't working?

Start by checking your call logs for clues. In Fuse's top-center ribbon menu, select Logs, then look for your call in the Session Log table.

When you find your call's log, select the View Logs icon to see a detailed view of interactions in the call. Each log entry corresponds to each module in your application. This will help you identify the issue or narrow down a list of possible issues. For example, if the SMS failed to send, an error message will show up for the SMS module's log entries.

Once you've checked the logs, open your application again, retrace your steps in this guide, and carefully check your work. Sometimes, a misplaced symbol, a missing connection between modules, typos in variable names, and other small issues can also cause an app to fail.

Save after making any needed revisions, and adjust your deployment if needed. From there, test and try again.

Conclusion

If your application works as intended in your test call, you receive your application's SMS message, and your call log shows no errors, then you have successfully used and tested Fuse's SMS module.

What can I do with this? The Fuse application you've just built covers the basics of the SMS module. Next, you can expand your application – and your Fuse knowledge – into real world use cases that can enhance how you do business.

Use cases for the SMS module

A quick SMS message is a great way to provide a customer with confirmation details after a call. Once you confirm that your customer has provided an SMS-enabled number, you can design your applications to provide follow-up communications.

Check out the following article to learn more about these use cases.

Combining SMS and Voice for better customer experiencesPlum Voice Documentation

Consider building a Fuse application for one of the SMS use cases presented in this article.

Additional reading and resources

• Shadow Variables: Describes shadow variables in Plum Fuse. Useful if you chose to do the optional change in Step 2.