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:

Property

Type

Description

shortenLinks

string

Choose from:
on
marked
off

The shortenLinks property should have one of the following values:

Value

Description

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

🚧

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:

Property

Type

Description

expiresOn

date-time

Date/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:

Property

Type

Description

title

string

The title to use to describe the message (if supported by the channel).

conversationId

string

Optional conversationId, used to correlate messages within the system and on any external channels, if supported.

metadata

object

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

channelOptions

object

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