Additional options

Link Shortening

You can optionally enable link shortening on your message's to save on the amount of characters you links take up in your messages. The messages body or plain/text message parts will be scanned if link shortening is enabled for any URLs and then they are replaced with a shortened version. It is possible to only shorten specific URLs within a message by using the marked URLs only value for the shortenLinks property, which can be useful when you want to shorten a long personalized URL but leave the corporate link unaltered.

A shortened URL will be between 22-28 characters in length. It will be served from one of our dotdigital shortening domains such as dd1.io. A typical example of a shortened link is:

https://dd1.io/a23Bdc1

🚧

Must be full URLs

For link shortening to recognize a URL please ensure they are full URLs i.e. they start with either https:// or http://

To enable link shortening add the shortenLinks property to your request with a value as follows:

PropertyTypeDescription
shortenLinks stringChoose from:
on
marked
off

The shortenLinks property should have one of the following values:

ValueDescription
on Shortens all URL links
marked Shorten only URLs prefixed with a @ symbol
off Do not link shorten

Example calls with link shortening

{
    "body": "A test message with link shortening http://login.dotdigital.com#will_be_shortened and https://dotdigital.com#will_be_shortened",
    "to": {
        "phoneNumber": "447123123123"
    },
    "shortenLinks": "on",
    "rules": [
        "sms"
    ]
}
{
    "body": "A test message with link shortening @http://dotdigital.com#will_be_shortened and https://dotdigital.com",
    "to": {
        "phoneNumber": "447123123123"
    },
    "shortenLinks": "marked",
    "rules": [
        "sms"
    ]
}

📘

Let your systems know when customers have interacted with links

You can receive interaction.click webhook events whenever any of your tracked links are clicked on by customers allowing you to trigger follow ups or track interactions within your own systems.

🚧

Only for the SMS channel

Please note link shortening is currently limited to the SMS channel only!

Setting Expiry

For time sensitive messages you can specify an expiry date and time where we won't deliver your message after. Where a channel supports message expiry, the expiry time is passed on automatically.

To set an expiry, set the following property:

PropertyTypeDescription
expiresOndate-timeDate/Time (in UTC, ISO 8601 format)

🚧

SMS Expiry times

Please ensure that your expiry time is more than 1 minute from the current UTC time, as when processed if the time difference between UTC and the expiry time is less than a minute, then the default expiry will be applied. 1 minute is the minimum validity for an SMS expiry.

{
  "body": "Test from the Omnichannel API",
  "to": {
    "phoneNumber": "447123123123"
  },
  "expiresOn": "2017-03-16T17:05:02Z",
  "rules": [
    "sms"
  ]
}
"expiresOn": "2017-03-16T17:05:02Z"

Others...

These other properties may be of use:

PropertyTypeDescription
titlestringThe title to use to describe the message (if supported by the channel).
conversationIdstringOptional conversationId, used to correlate messages within the system and on any external channels, if supported.
metadataobjectCustom metadata relating to the message that is echoed back to you on any webhook events related to the message.

Can be used to correlate events back to sends, and aid webhook processing efficiency.

Ideal for use with webhooks for reporting and billing data collection.
channelOptionsobjectAllows configuration of popular options for a channel without the need for a full customBody. See each channel's details for further information.
{
  "body": "Hi, just letting you know that your order #1234 has been dispatched",
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "sms"
  ],
  "metadata": {
    "data": "My correlation data",
    "moreData": "You can hold any structured JSON data!"
  }
}