Channel identifier

In the API this channel can be referenced using: sms.

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

Send an SMS

To send an SMS through the Enterprise Communications API you must:

ensure that your channel rules include the sms channel
specify either a phoneNumber in international format or a profileId with a phone number in the to section of your request
provide a body message, for example:

{
  "body": "Sending is easy with the One 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/3rdparty/comapi/images/laptop.png"
    }
  ]
}

📘
Message length
The maximum supported length of SMS messages is 2000 characters.

🚧
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.

Localiser and stitching

In the basic SMS send example above, we haven’t defined what phone number or identifier the SMS is sent from. You might be wondering how this can work. The answer is that we 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 is used for all future SMS communications within a 60 day period. This keeps 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 an object with your options in the request’s channelOptions section in the sms property.

Property

Type

Description

from

string

The phone number, alpha identifier, or short code you're sending from.

allowUnicode

Boolean

Determines whether Unicode characters are allowed in the message body or not.

Learn more in the section Why Unicode is important.

unicodeConversion

Unicode conversion settings object

The settings for controlling automatic Unicode conversion

Unicode conversion settings object

Property	Type	Description
convertUnicodeToGsm	Boolean	Determines whether we 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 One API is easy!",
  "to": {
    "phoneNumber": "447123123123"
  },
  "channelOptions": {
  	"sms": {
  		"from": "Acme",
  		"allowUnicode": true
  	}
  },
  "rules": [
    "sms"
  ]
}

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

{
  "body": "Dzień dobry, w czym mogę pomóc?",
  "to": {
    "phoneNumber": "447990766636"
  },
  "channelOptions": {
    "sms": {
      "from": "Comapi",
      "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.

You can rent these from us for your desired country.

Short Code

60006

A short numeric identifier that requires companies to register for.

You can rent these from us for your desired country.

Alpha

Acme

String value between 2-11 characters of 0-9, a-z, A-Z, hyphen, underscore, full stop, and space

Why Unicode is important with SMS

By default, SMS is limited to a small character set called the GSM character set.

If your message body contains characters outside of the GSM character set, you must have the allowUnicode channel option enabled 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, therefore the numbers of characters you can fit into an SMS segment is severely affected. A message using 160 characters which only uses the GSM character set costs one SMS. If the message contains a Unicode character, the same message costs three SMS.
Learn more in SMS message length and Unicode.

Automatically remove Unicode characters

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 tries to map Unicode characters to a visually similar character in the GSM alphabet, for example, the character ą would be mapped to a, or ś to s.

To enable this feature, specify a unicodeConversion object and ensure that convertUnicodeToGsm is set to true. You can also specify custom replacement character mappings if you want to.

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 tries to convert most common Unicode characters used in Latin-based character sets to a GSM equivalent, but we cannot guarantee that it can detect and replace them all.
If there are specific mappings you want to address, you can add your own character mappings 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

If you only define the body property when sending a message, the Enterprise Communications API automatically creates a text-based SMS message, but you can specify advanced options if you use the customBody property and define an sms object within it:

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). You must still include the phoneNumber in the to block.
`from`*	string	A string containing the from value.
`countryIsoCode`	string	An optional country in ISO 3166-1 alpha-3 format. If specified, the to field can contain a number in local format, for example, 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 are not sent. Learn more inWhy Unicode is important. If you’re unsure we recommend it is set to `true`.

Example

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "customBody": {
    "sms": {
      "from": "Acme Corp",
      "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
When using the customBody option with the SMS channel you still need to specify the phoneNumber in the to block, as this is used for profile identification.

📘
customBody and channelOptions
It's not possible to define a customBody and channelOptions together in the same request, as the system doesn't know which settings to use, so either use the universal send with channelOptions or define everything using a customBody.

Receipts and inbounds

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.

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.

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 event in the payload > channelData node:

"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:

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.

Learn more.

📘
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, such as customer or campaign.

Tracking activity for Campaign Manager sends

If you use our Campaign Manager tool to send campaigns but would like to track activity then you can do so using the SMS receipts as described above.

For messages sent from Campaign Manager we automatically include the Campaign details in the metadata so you can correlate the activity back to a campaign. The metadata can be found in the webhook message events payload > metadata field.

"metadata": {
            "comapiSystem": "smsApi",
            "campaignManager": {
                "campaignId": 340428,
                "campaignName": "A Test Campaign"
            }
        }

{
    "eventId": "feed1049-6785-4ed3-8cf0-d902cb8fa94f",
    "accountId": 1234,
    "apiSpaceId": "ff42e8af-5fc3-40d4-a38c-034535c0a385",
    "name": "message.delivered",
    "payload": {
        "id": "80e63fb7-637a-4a85-9d86-75f91f5d018d",
        "details": {
            "channel": "sms",
            "channelStatus": {
                "messageId": "80e63fb7-637a-4a85-9d86-75f91f5d018d",
                "statusId": 1,
                "statusTime": "2019-03-06T11:05:46.690Z",
                "transid": "78262982",
                "messageguid": "8403e3b0-c42a-4dc2-9395-b6ac34dfe68f",
                "statusid": "1",
                "recipient": "447990766636",
                "statusdescription": "Messages delivered to handset",
                "datetime": "2019-03-06T11:06:02.093",
                "clientref": "",
                "submissiontime": "2019-03-06T11:05:44.760",
                "apispaceid": "FF42E8AF-5FC3-40D4-A38C-034535C0A385",
                "statustimeutc": "2019-03-06T11:05:46.690Z"
            }
        },
        "metadata": {
            "comapiSystem": "smsApi",
            "campaignManager": {
                "campaignId": 340428,
                "campaignName": "Test"
            }
        },
        "updatedOn": "2019-03-06T11:05:46.690Z"
    },
    "revision": 2,
    "etag": "\"2e-d73NE1jo1Opl1Rr3+nbymTqNYpk\"",
    "timestamp": "2019-03-06T11:06:05.401Z"
}

The metadata contains:

Path	Field	Description
campaignManager	campaignId	The unique numeric identifier for the campaign.
campaignManager	campaignName	The text-based campaign name the user gave the campaign.

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 event in the payload > channelStatus > sms node.

"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"
}

Useful fields:

Path

Field

Description

Example

sms.details

reason

The reason for the failure, In English.

Rejected by operator.

sms.details.data

statusid

An integer message status for the reason the message failed.

Possible values.

4

sms.details.data

statustimeutc

This is the UTC time that the status was set

2019-04-12T09:46:00.000Z

📘
Quick start
Check out our Sending SMS quick start for a simple code example of how to send SMS.