The Link Shortening feature is only available for use with Messaging Services.
Link Shortening is part of Engagement Suite. Visit the SMS Pricing page and WhatsApp Pricing page for price details..
Link Shortening is a Messaging Services feature that allows you to send messages with shortened links using your own company-branded domain. Twilio also provides click tracking with the Link Shortening feature, so you can track customer engagement with your messages' shortened links.
When Link Shortening is used, Twilio converts long links from a message body and converts them to unique shortened links. The shortened links contain your Link Shortening domain, followed by ten alphanumeric characters.
Link Shortening and click tracking are included in Engagement Suite. For information on Engagement Suite pricing, see the pricing pages for SMS/MMS or WhatsApp.
With Link Shortening, Twilio turns a message that looks like this:
Visit this link to start earning rewards today! https://twilio.com/N6uAirXeREkpV2MW7kpV2MW7...
into a message that looks like this:
Visit this link to start earning rewards today! https://twil.io/j9kj9K3huK9u7...
You need to own the domain you use for link shortening (like how Twilio owns twil.io).
Consider the following scenario:
https://twil.io
Body
contains the following:
1Thanks for signing up for Acme, Inc. rewards!2Click on the link to start saving today! https://twilio.com/kpV2MWAvh1zn4gET1zn4gEFkpVAvh1bAvh1zn4gEF
Does your link contain special characters? If so, make sure to encode them in the message body in order for the URL to remain valid.
At send time, Twilio:
https://twilio.com/kpV2MWAvh1zn4gET1zn4gEFkpVAvh1bAvh1zn4gEF
to
https://twil.io/j9K3huK9u7
Body
of the message.
1Thanks for signing up for Acme, Inc. rewards!2Click 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:
To
parameter of the original Message)
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:
Property | Description |
---|---|
event_type | The type of event. The value is click or preview . |
sms_sid | The SID of the Message resource that contained the shortened link. |
to | The To value of the original Message resource. This is the recipients phone number or channel address (e.g. whatsapp:+15558887474 ) |
from | The From number of the Message. This is a phone number or channel address from your Messaging Service's sender pool. |
link | The original long link. This shortened link redirected to this link. |
click_time | The ISO 8601 timestamp of when the customer clicked on the shortened link or when the link preview was generated. |
messaging_service_sid | The SID of the Messaging Service that sent the Message. |
account_sid | The SID of the Twilio Account that sent the Message. |
user_agent | The user agent that accessed the link. Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) |
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.
Link Shortening only works after you've completed the steps in the onboarding guide. You should read the rest of this page before you begin onboarding.
Does your link contain special characters? If so, make sure to encode them in the message body in order for the URL to remain valid.
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
.
ShortenUrls
parameter's value must be
true
.
MessagingServiceSid
parameter value must be the SID of the Messaging Service associated with your Link Shortening domain.
To
parameter, which is required for all Messages
Body
parameter
The code sample below shows how to send an SMS message with a shortened link.
POST
request contains the required
To
,
ShortenUrls
and
MessagingServiceSid
parameters, and the
Body
parameter contains a long link (not shortened).
When you send a link shortening POST
request, the body
parameter in the response will contain the original URL. This is because the status
of the message is queued
. For more details on message statuses, please review Initial status of a Message resource.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createMessage() {11const message = await client.messages.create({12body: "Visit this link to start earning rewards today! https://example.com/N6uAirXeREkpV2MW7kpV2MW7TAvh1zn4gEFMTAvh1zn4gEFMN6uAirXeRE",13messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",14shortenUrls: true,15to: "+15272727727",16});1718console.log(message.body);19}2021createMessage();
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.
GET
request contains the required Message
Sid
parameter.
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.
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/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createMessage() {11const message = await client.messages.create({12body: "Visit this link to start earning rewards today! https://example.com/N6uAirXeREkpV2MW7kpV2MW7TAvh1zn4gEFMTAvh1zn4gEFMN6uAirXeRE",13messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",14shortenUrls: true,15to: "whatsapp:+15551212121",16});1718console.log(message.body);19}2021createMessage();
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:
POST
request to create Message resource with
ShortenLinks
set to
true
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.