Link Shortening

Consider the following scenario:

• You've onboarded your domain and Messaging Service for Link Shortening
• Your Link Shortening domain is https://twil.io
• You create a Message with a link you want to shorten. The Body contains the following:

1
Thanks for signing up for Acme, Inc. rewards!
2
Click on the link to start saving today! https://twilio.com/kpV2MWAvh1zn4gET1zn4gEFkpVAvh1bAvh1zn4gEF

At send time, Twilio:

• Creates a redirect from https://twilio.com/kpV2MWAvh1zn4gET1zn4gEFkpVAvh1bAvh1zn4gEF to https://twil.io/j9K3huK9u7
• Replaces the long link in the Body of the message.
• The recipient receives the following message:

1
Thanks for signing up for Acme, Inc. rewards!
2
Click on the link to start saving today! https://twil.io/j9K3huK9u7

Twilio stores original link/shortened link association information for 90 days. Within those 90 days, clicks on the shortened link are redirected to the original long link.

After 90 days, the link "expires." If a customer clicks on an expired shortened link, they are redirected to a fallback URL and click events are no longer sent to your callback URL.

The fallback URL is configured when you set up Link Shortening.

The Link Shortening feature also allows you to receive data whenever a customer clicks on a shortened link. Device-generated link previews are also distinguishable in the click event type. You can use this information to measure marketing campaign effectiveness, track individual recipient engagement, and/or implement a customized workflow whenever a shortened link is visited.

For each "click event", Twilio sends a POST request to your provided endpoint containing details about the event such as:

• The type of click event: click or preview
• The number or channel address of the recipient (i.e. the To parameter of the original Message)
• The original long link that was shortened
• The time the recipient clicked on the link

An example of a click event callback request from Twilio is shown below:

1
{
2
  "event_type": "click",
3
  "sms_sid": "SMxxx",
4
  "to": "+15554567890",
5
  "from": "+15557654321",
6
  "link": "https://www.longlink.com/original_link",
7
  "click_time": "2022-10-24T17:17:26.529Z",
8
  "messaging_service_sid": "MGxxx",
9
  "account_sid": "ACxxx",
10
  "user_agent": "some_user_agent"
11
}
12

The table below describes each property in click event callback requests from Twilio:

You can configure a click event callback URL when you onboard with Link Shortening.

Twilio doesn't send click event information once a link has expired or outside of your Messaging records retention period (see below).

Click event information is also available via Event Stream subscription.

If you've configured a custom retention period for your Messaging records, make sure your retention period is at least 90 days. (By default, the retention period is 400 days.)

Although shortened links are valid for 90 days, click events are not generated beyond your Account's retention period.

To configure your custom retention period, open your Console and go to Develop > Messaging > Settings > General > Message Records Data Access and Backup.

To send a message with a shortened link, send a POST request to the Messages list URI (like you do for messages without shortened links) with two additional parameters: ShortenUrls and MessagingServiceSid.

• The ShortenUrls parameter's value must be true.
• The MessagingServiceSid parameter value must be the SID of the Messaging Service associated with your Link Shortening domain.
• You must also include the To parameter, which is required for all Messages
• The link you wish to shorten is included in the Body parameter

The code sample below shows how to send an SMS message with a shortened link.

• The POST request contains the required To, ShortenUrls and MessagingServiceSid parameters, and the Body parameter contains a long link (not shortened).

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    body: "Visit this link to start earning rewards today! https://example.com/N6uAirXeREkpV2MW7kpV2MW7TAvh1zn4gEFMTAvh1zn4gEFMN6uAirXeRE",
13
    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14
    shortenUrls: true,
15
    to: "+15272727727",
16
  });
17

18
  console.log(message.body);
19
}
20

21
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "Visit this link to start earning rewards today! https://example.com/N6uAirXeREkpV2MW7kpV2MW7TAvh1zn4gEFMTAvh1zn4gEFMN6uAirXeRE",
5
  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": "+14155552345",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "tags": {
23
    "campaign_name": "Spring Sale 2022",
24
    "message_type": "cart_abandoned"
25
  },
26
  "to": "+15272727727",
27
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

The code sample below shows how to retrieve the previously sent SMS containing the shortened URL.

• The GET request contains the required Message Sid parameter.
• The resulting SMS message received by the customer contains a shortened link.

GET "https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json"

1
{
2
    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
    "api_version": "2010-04-01",
4
    "body": "Visit the link to start earning rewards today! https://example.com/j9kj9K3huK",
5
    "date_created": "Thu, 30 Jul 2015 20:12:31 +0000",
6
    "date_sent": "Thu, 30 Jul 2015 20:12:33 +0000",
7
    "date_updated": "Thu, 30 Jul 2015 20:12:33 +0000",
8
    "direction": "outbound-api",
9
    "error_code": null,
10
    "error_message": null,
11
    "from": "+15555238886",
12
    "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
13
    "num_media": "0",
14
    "num_segments": "1",
15
    "price": null,
16
    "price_unit": null,
17
    "sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
18
    "status": "sent",
19
    "subresource_uris": {
20
        "media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
21
    },
22
    "to": "+15551212121",
23
    "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
24
}

The code sample below shows how to send a WhatsApp message with a shortened link. This assumes that you've onboarded your WhatsApp Business Account with Twilio.

• The POST request contains the required To, ShortenUrls and MessagingServiceSid parameters, and the Body parameter contains a long link (not shortened).
• The resulting WhatsApp message received by the customer contains a shortened link.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    body: "Visit this link to start earning rewards today! https://example.com/N6uAirXeREkpV2MW7kpV2MW7TAvh1zn4gEFMTAvh1zn4gEFMN6uAirXeRE",
13
    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14
    shortenUrls: true,
15
    to: "whatsapp:+15551212121",
16
  });
17

18
  console.log(message.body);
19
}
20

21
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "Visit this link to start earning rewards today! https://example.com/N6uAirXeREkpV2MW7kpV2MW7TAvh1zn4gEFMTAvh1zn4gEFMN6uAirXeRE",
5
  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": "+14155552345",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "tags": {
23
    "campaign_name": "Spring Sale 2022",
24
    "message_type": "cart_abandoned"
25
  },
26
  "to": "whatsapp:+15551212121",
27
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

Link Shortening has an Account-based rate limit of 2000 requests per second.

Twilio shortens links at send time. Therefore, Twilio receives a "Link Shortening request" in the following situations:

• When Twilio receives a POST request to create Message resource with ShortenLinks set to true
• At the SendTime of a scheduled message with ShortenLinks set to true

If you exceed the rate limit, messages are not sent and a 20429 error code is emitted.

If there is an error with Link Shortening (e.g. changes to your domain verification or an expired certificate), you can tell Twilio to send messages with the original long links or to not send the messages.

The default behavior is to continue sending messages with the original long links. This may result in multiple message segments, which may incur higher costs. This setting only affects Messages with a ShortenUrls parameter set to true.

You can configure this preference when you set up Link Shortening on your account.

• Get started with Link Shortening by following the onboarding guide