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"
}
]
}
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) Note you must still stipulate the phoneNumber in the to 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 |