🚧
Are you ready to send SMS within your target countries?
The ability to send SMS via the Omnichannel API is restricted to accounts that have SMS pay as you go enabled, so please contact us if you want this enabled.
Sending SMS internationally can be complex as each country has their own regulations and requirements for businesses sending SMS, such as being pre-registered to send, only using shortcodes, specific opt-in and opt-out requirements etc...
Please contact us to discuss your SMS requirements prior to using the API to avoid issues.

🚧
We do not use the suppression lists!
As the API has been designed for real-time transactional SMS sends we do not apply the suppression lists to the sends, therefore if you ask us to send an SMS we will attempt to do so. Only sends from the SMS campaign tool and automation programs use the suppression lists.

📘
Check out our Send an SMS recipe to understand the basics of how to send SMS
See Send an SMS to see how the API works for sending SMS messages, or our Sending SMS messages quick start

Channel Identifier

In the API this channel can be referenced using: sms

This identifier can be used in the rules array, and customBody sections.

Sending an SMS

Sending an SMS via the Omnichannel API is very simple all you required to so is ensure that your channel rules include the sms channel and you specify either a phoneNumber in international format or a profileId with a phone number in the to section of your request, and provide a body message e.g.

{
  "body": "Sending is easy with the Omnichannel API",
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "sms"
  ]
}

{
  "title": "Your order has been dispatched",
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "sms"
  ],
  "messageParts": [
    {
      "name": "Body text",
      "type": "text/plain",
      "data": "Your order: ABC1245 has been dispatched."
    },
    {
      "type": "image/png",
      "url": "http://cdn.dnky.co/cpaas/images/laptop.png"
    }
  ]
}

🚧
SMS can be the target of AIT attacks, so ensure you have protection
Protect your application from automated attacks that exploit SMS and voice endpoints to generate fraudulent charges.
If you use SMS or voice API endpoints in your customer flows, you need to understand AIT (Artificially Inflated Traffic) attacks and how to defend against them. Please read our article of AIT to ensure you understand the threat and how you can protect your systems from it.

Message Length

The maximum length of SMS messages supported is 2000 characters.

Localiser & Stitching

In the basic SMS send example above you will notice we have not defined what phone number or identifier the SMS is sent from, so how can this work? The answer is that we will automatically assign a suitable from phone number for the destination country from a pool of numbers. If your message is sent from a pool number, that number is then stitched to the destination phone number, and will be used for all future SMS communications within a 60 day period - keeping the individual user experience consistent.

Channel Options

The following additional channel options can be used to control the SMS channels most common options. To use the channel options create a object with your options in the requests channelOptions section in the sms property:

Property

Type

Description

from

string

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

allowUnicode

boolean

This toggles whether having Unicode characters in the message body will be allowed or not

Please read why Unicode is important below before using this setting

unicodeConversion

Unicode conversion settings object

The settings for controlling automatic Unicode conversion

Unicode conversion settings object

Property	Type	Description
convertUnicodeToGsm	boolean	This toggles whether we will try to convert Unicode characters to their closest match in the GSM character set or not
customReplacements	array (Replacement object)	A list of specific Unicode character mappings to apply to the Unicode conversion overriding the default mappings

Replacement object

Property	Type	Description
from	string	The single Unicode character to map from
to	string	The GSM character to map to

{
  "body": "Sending SMS with the Omnichannel API is easy!",
  "to": {
    "phoneNumber": "447123123123"
  },
  "channelOptions": {
  	"sms": {
  		"from": "YourCompany",
  		"allowUnicode": true
  	}
  },
  "rules": [
    "sms"
  ]
}

{
    "body": "A test message sent with unicode enabled for emoji 😁👍✔!",
    "to": {
        "phoneNumber": "447123123123"
    },
    "channelOptions": {
        "sms": {
            "from": "YourCompany",
            "allowUnicode": true
        }
    },
    "rules": [
        "sms"
    ]
}

{
  "body": "Dzień dobry, w czym mogę pomóc?",
  "to": {
    "phoneNumber": "447123123123"
  },
  "channelOptions": {
    "sms": {
      "from": "YourCompany",
      "allowUnicode": false,
      "unicodeConversion": {
        "convertUnicodeToGsm": true
      }
    }
  },
  "rules": [
    "sms"
  ]
}

{
  "body": "Dzień dobry, w czym mogę pomóc?",
  "to": {
    "phoneNumber": "447990766636"
  },
  "channelOptions": {
    "sms": {
      "from": "YourCompany",
      "allowUnicode": false,
      "unicodeConversion": {
        "convertUnicodeToGsm": true,
        "customReplacements": [
          {
            "from": "ó",
            "to": "o"
          },
          {
            "from": "ń",
            "to": "n"
          }
        ]
      }
    }
  },
  "rules": [
    "sms"
  ]
}

Possible from values

You can send SMS from the following types of originator:

Type	Example	Description
Mobile number	447123123123	A mobile number in international format. These can be rented for your desired country from us.
Short Code	60006	A short numeric identifier that requires companies to register for. These can be rented for your desired country from us.
Alpha	dotdigital	String value between 3-11 characters of 0-9, a-z, A-Z, hyphen, underscore, full-stop and space.

Why is Unicode important with SMS

SMS by default is limited to a small character set called the GSM character set. If you body contains characters outside of the GSM character set, such as emoji, it will require the allowUnicode channel option to be enabled if you want to be able to send the message.

❗️
Unicode SMS messages can cost up to 3 times more!
Unicode messages require over double the amount of data to be sent over mobile networks and therefore the numbers of characters you can fit into a SMS segment is severely affected i.e. A message using 160 characters which only uses the GSM character set will cost 1 SMS, whereas if it has a Unicode character the same message will cost 3 SMS.
Please see our knowledge base article on how message lengths are calculated for SMS.

How to remove Unicode characters automatically

We offer an optional feature for the SMS channel to convert Unicode characters to GSM based characters, which could possibly save you money on your messaging. This feature will try to map Unicode characters to a visually similar character in the GSM alphabet e.g. the character ą would be mapped to a, or ś to s

To enable this feature specify a unicodeConversion object and ensure the convertUnicodeToGsm is set to true, and specify a custom replacement character mappings if required.

With the option enabled the following message is converted from "Dzień dobry, w czym mogę pomóc?" to "Dzien dobry, w czym moge pomoc?" removing all the Unicode characters automatically.

❗️
Replacements not Guaranteed
The library will try to convert most common Unicode characters used in Latin based character sets to a GSM equivalent, but we cannot guarantee it will detect and replace them all. You may however add your own character mappings if there are specific mappings you want to address by specifying an array of mappings in the customReplacements array under the unicodeConversion node. A custom set of mappings replaces the default set.

Custom Body

The Omnichannel API automatically creates a text based SMS message if you only define the body property when sending a message, but you can specify advanced options if you use the customBody property and define a sms object within it using the details below:

Property	Type	Description
`to`*	string	The phone number to send to. This should be in international format (e.g. 447123123456), or if countryIsoCode is specified, in local format (e.g. 07123123456) Noteyou must still stipulate thephoneNumberin theto* block!
`from`*	string	A string containing the from value. See the possible options above
`countryIsoCode`	string	An optional country in ISO 3166-1 alpha-3 format. If specified, the to field can contain a number in local format, e.g. GBR would allow 07123123456
`body`*	string	The message text
`deliverAfter`	datetime	A date time specifying when we should try to deliver the message. This must be a UTC time in ISO 8601 format, e.g. 2015-10-21T13:28:06.419Z
`validUntil`	datetime	A date time specifying how long we should try to deliver the message for. This must be a UTC time in ISO 8601 format, e.g. 2015-10-21T13:28:06.419Z
`rejectUnicode`	boolean	If set to true, any messages containing Unicode characters will not be sent. Please read why Unicode is important below before using this setting. If not sure we recommend it is set to true

Examples of sends using SMS custom bodies are:

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "customBody": {
    "sms": {
      "from": "YourCompany",
      "to": "447123123123",
      "body": "Hello, this is a message using a SMS customBody",
      "deliverAfter": "2017-03-01T12:57:00.543Z",
      "rejectUnicode": "true"
    }
  },
  "rules": [
    "sms"
  ]
}

🚧
Ensure you specify a "to" block still!
When using the customBody option with the SMS channel you still need to specify the phoneNumber in the to block as this will be used for profile identification.

🚧
Cannot use a customBody and channelOptions together
It's not possible to define a customBody and channelOptions together in the same request as we won't know which settings to use, so either use the universal send with channelOptions or define everything using a customBody

Receipts and Inbounds

To receive feedback or inbound messages from SMS sends please see the following:

Inbound SMS

Allows you to receive SMS messages sent from phones to your hosted virtual mobile numbers, short codes or keywords. Messages are delivered to a URL of your choosing using the webhook system. See the Inbound event in the Message Events section for more details.

Receipts

If you need to to know the status of messages you've sent using one of our APIs, you can request that delivery receipts are forwarded to a URL of your choosing using the webhook system. See the events in the Message Events section for more details on the receipt events you can receive.

You can receive the following types of receipts:

Sent
Delivered
Expired
Failed

SMS Specific Channel Data

The SMS channel carries the following extra channel specific data within the message.sent webhook events which may be of use in your integrations. The channel data can be found in the message.sent webhook events in the payload -> channelData node as illustrated below:

"channelData": {
      "sms": {
        "phoneNumberCountryCode": "GB",
        "segmentCount": 1
      }
    }

{
    "eventId": "749ad116-2682-4911-be99-db79b5ba2e33",
    "accountId": 1234,
    "apiSpaceId": "ff42e8af-5fc3-40d4-a38c-034535c0a385",
    "name": "message.sent",
    "payload": {
        "id": "164442aa-e8d5-42e0-a85e-5d8ae2bcf494",
        "details": {
            "additionalInfo": {
                "source": "mirroring"
            },
            "channel": "sms",
            "channelStatus": {
                "transid": "78263001",
                "messageguid": "70f20e65-702d-4faa-852d-061adaf5e7f0",
                "statusid": "3",
                "recipient": "447990766636",
                "statusdescription": "Messages queued for delivery at SMSC",
                "datetime": "2019-03-06T13:54:31.147",
                "clientref": "164442aa-e8d5-42e0-a85e-5d8ae2bcf494",
                "submissiontime": "2019-03-06T13:54:12.357",
                "apispaceid": "FF42E8AF-5FC3-40D4-A38C-034535C0A385",
                "statustimeutc": "2019-03-06T13:54:14.247Z"
            }
        },
        "channelData": {
            "sms": {
                "phoneNumberCountryCode": "GB",
                "segmentCount": 1
            }
        },
        "metadata": {
            "data": "My correlation data"
        },
        "updatedOn": "2019-03-06T13:54:14.247Z"
    },
    "revision": 3,
    "etag": "\"2e-Zr4UILuvoEj64dGhAyg9Bm5bHYs\"",
    "timestamp": "2019-03-06T13:54:31.122Z"
}

The data is as follows:

Path	Field	Description
sms	phoneNumberCountryCode	The 2 character country code the number sent to belongs to
sms	segmentCount	The number of chargeable SMS segments this message uses. See our knowledge base for more info on SMS message segment counts

📘
Monitor activity for billing purposes
You can use the message.sent receipts SMS channel data to create your own billing data. Use the payload->channelData->sms->segmentCount field to record the SMS charges for a message, and the payload->metadata to help you correlate what the message relates to i.e. customer / campaign etc...

Additional Error Details

If you need to understand the exact reason an SMS failed to deliver or send then additional details can be obtained from within the message.failed webhook event for SMS channel sends.

The details can be found in the message.failed webhook events in the payload -> channelStatus -> sms node as illustrated below:

"channelStatus": {
                "sms": {
                    "status": "failed",
                    "details": {
                        "reason": "Rejected by operator",
                        "data": {
                            "tranid": "78303243",
                            "messageguid": "a88cf899-07dc-47c0-873f-f2dba2dc35f1",
                            "statusid": "4",
                            "recipient": "447123123123",
                            "statusdescription": "Messages rejected by operator",
                            "datetime": "2019-04-12T10:47:00.237",
                            "clientref": "37fe6fcc-8149-48d0-baf9-1c72850d532b",
                            "submissiontime": "2019-04-12T10:41:13.073",
                            "apispaceid": "AE1F5482-2438-41CE-AC1A-9137491F701D",
                            "statustimeutc": "2019-04-12T09:46:00.000Z"
                        }
                    },
                    "updatedOn": "2019-04-12T09:46:00.000Z"
                }
            }

{
    "eventId": "c14320d9-6f24-48c6-a981-15879b756203",
    "accountId": 1234,
    "apiSpaceId": "ae1f5482-2438-41ce-ac1a-9137491f701d",
    "name": "message.failed",
    "payload": {
        "id": "37fe6fcc-8149-48d0-baf9-1c72850d532b",
        "details": {
            "channelStatus": {
                "sms": {
                    "status": "failed",
                    "details": {
                        "reason": "Rejected by operator",
                        "data": {
                            "tranid": "78303243",
                            "messageguid": "a88cf899-07dc-47c0-873f-f2dba2dc35f1",
                            "statusid": "4",
                            "recipient": "447123123123",
                            "statusdescription": "Messages rejected by operator",
                            "datetime": "2019-04-12T10:47:00.237",
                            "clientref": "37fe6fcc-8149-48d0-baf9-1c72850d532b",
                            "submissiontime": "2019-04-12T10:41:13.073",
                            "apispaceid": "AE1F5482-2438-41CE-AC1A-9137491F701D",
                            "statustimeutc": "2019-04-12T09:46:00.000Z"
                        }
                    },
                    "updatedOn": "2019-04-12T09:46:00.000Z"
                }
            },
            "reason": "Channel reported the message was undeliverable"
        },
        "metadata": {
            "data": "My correlation data"
        },
        "updatedOn": "2019-04-12T09:46:00.000Z"
    },
    "revision": 4,
    "etag": "\"2e-9e8qfTZb9PDAQGEExbOz24FWjPk\"",
    "timestamp": "2019-04-12T09:47:00.657Z"
}

The fields of interest in the SMS channels channelStatus block are as follows:

Path	Field	Description	Example
sms.details	reason	The English reason for the failure	Rejected by operator
sms.details.data	statusid	This is a integer message status for the reason the message failed. It will be one of these values	4
sms.details.data	statustimeutc	This is the UTC time that the status was set	2019-04-12T09:46:00.000Z