Sending SMS using Dotdigital Omnichannel and Ruby

This short tutorial will show you how to send SMS using the Dotdigital Omnichannel 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 Dotdigital API user credentials and a target mobile number.

To create an API User please see this tutorial

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 Pay As You Go billing enabled on your account first; talk to your account manager if you need this enabling please.

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

ruby send_sms.rb

Alternatively in IDE's simply run the file send_sms.rb

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

Understanding the code

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

RESTful APIs

The Dotdigital Omnichannel API is RESTful and therefore utilizes the abilities of the HTTP protocol in order to derive action and context.

In the tutorial the URL we POST to contains the action or entity we are interested in and the HTTP verb POST indicates we want to send a message.

Authentication is very easy as it uses the HTTP protocols basic auth, with a set of API User credentials.

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 Omnichannel 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 dotdigital 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 is set as basic auth using your Dotdigital API user credentials
• 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

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

Dotdigital Omnichannel 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 batch send endpoint (URL) is slightly different to the single send endpoint with /batch appended. The web method on being successfully called returns an array of messageId, one for each submitted message request.

To run simply apply your Dotdigital Omnichannel 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.