Sending SMS using Enterprise Communications API and Ruby

This short tutorial will show you how to send SMS using the Enterprise Communications API; it's quick and easy!

The tutorial's navigation controls are located above this text. Use to move to the next step of the tutorial. Use to move to the previous step of the tutorial (if there is one). Use to see an overview of all the steps in the tutorial.

To begin with you will need the following prerequisites installed:

• Ruby 2.3.x

Enter your details

To get the tutorial code to run successfully you need to enter your API Space details, security token and target mobile number.

Enter you API Space Id

Enter your API Space Id, this is used to identify the partition Enterprise Communications API uses for data storage and configuration.

To find your API Space Id you can select which API Space you want to work with by selecting it from the API Space drop down at the top of the page in the Enterprise Communications API portal. (Highlighted in yellow below)

Once selected open the API Space configuration section by clicking on the Hub -> API Space Details menu item on the left of the page and your API Space Id will be shown along with other details. (Highlighted in green below)

Enter you access token

Enter your access token, this is used to authenticate and authorise your API calls to Enterprise Communications API. Ensure your token has permissions to send messages and use the SMS channel.

If you need to create an access token you can do so by clicking on the Access Tokens option in the Hub section of the left hand menu. Click the Add new access token button and fill in the Name and Profile fields. The Name field describes the access token or its intended purpose such as the system that will use it. The ProfileId field is for setting the identity for the token i.e. the Enterprise Communications API profile this token represents. This is particularly useful for App Messaging where you want to message users as a virtual system user.

There are a many different sets of permissions to choose from, but for our purposes simply select all the One API Access - All Channels + Branch, as we want our system to send messages on any channel.

Now scroll to the bottom of the page and hit Create

Your access token will be shown with a convenient copy button on the right hand side (highlighted in green below) Ensure you copy this now and store it somewhere safe as it cannot be retrieved once you have navigated away from this page for security reasons.

Enter you mobile number

Enter your mobile number in international format, which is:

• Your country code i.e. 44 for the UK
• Your mobile number with any leading zeros removed e.g. if your local number is 07123 123 123 you would use 71234123123
• Remove any non numeric characters

e.g. If you lived in the UK and had a mobile number of 07123 123123 then in international format it would be 447123123123

Running the code

You are now ready to run the code and send an SMS, but please ensure you have some credit on your account first!

To run simply open a console in your tutorial folder and run:

Ruby send_sms.rb

You should recieve your SMS shortly, if a successful response was returned.

Understanding the code

The Enterprise Communications API is very easy to use, we'll just explain what the code is this tutorial does.

RESTful APIs

The Enterprise Communications API is RESTful and therefore utilises the abilities of the HTTP protocol in order to derive action and context.

In the tutorial the URL we POST to contains the API Space we want to send from and the HTTP verb POST indicates we want to send a message.

The Request object

The request object is used to describe the message you want to send and via what channels. As a minimum it is composed of:

body

The body is the text message body you want to send. The Enterprise Communications API will automatically ensure this message can be sent on any supported channels.

to

The to object should be populated with any addressing information that might be used by the channels you want to send on, such as:

• phoneNumber
• email
• fbMessengerId
• etc...

No from?

You don't need to define who the SMS is from by default as this will simply tell Enterprise Communications API you want it to select an appropriate from for the destination country using its Localizer and Stitching feature.

See our full documentation for more details.

The Request object with channel options

The request object can optionally have additional channelOptions defined to allow you finer control over the SMS send, options are:

from

The from is the phone number, alpha identifier, or short code you are sending from.

allowUnicode

The allowUnicode options toggles whether having Unicode characters in the message body will be allowed or not.

See our full documentation for more details.

Setting the HTTP headers

We prepare the HTTP header to be passed with the web request which include:

• authorization with our access token to authorise the call
• content-type to indicate the body is JSON
• accept to indicate we want a JSON response
• cache-control to indicate we don't want responses cached

Creating the URL

As Enterprise Communications API is RESTful its URLs are used describe the context, in this case which API Space should be used when sending messages.

Calling the web service

We use the headers and URL to perform a HTTP POST and read the response and status code.

To run simply open a console in your tutorial folder and run:

ruby send_sms_with_options.rb

Batch Sending

Enterprise Communications API also supports the sending of messages in a batch which should be used when their is more than one recipient as it will be much more efficient than calling the single send method multiple times.

The web method is very simple as it accepts an array of message requests as used in the single submission method described in this tutorial. The web method on being successfully called returns an array of messageId, one for each submitted message request.

To run simply apply your Enterprise Communications API settings like you did for the single send and then open a console in your tutorial folder and run:

ruby batch_send_sms.rb

See our full documentation for more details.

All done

Thanks for taking the time to look through the tutorial, to find out more visit our full documentation.