Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Link Shortening



The Link Shortening feature is only available for use with Messaging Services.

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(link takes you to an external page) or WhatsApp(link takes you to an external page).

With Link Shortening, Twilio turns a message that looks like this:

Visit this link to start earning rewards today!

into a message that looks like this:

Visit this link to start earning rewards today!

You need to own the domain you use for link shortening (like how Twilio owns

Track customer engagement with click events

track-customer-engagement-with-click-events page anchor

The Link Shortening feature also allows you to receive data whenever a customer clicks on a shortened link. You can 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 each "click event", Twilio sends a POST request to your provided endpoint containing details about the event such as:

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

"event_type": "click",
"sms_sid": "SMxxx",
"to": "+15554567890",
"from": "+15557654321",
"link": "",
"click_time": "2022-10-24T17:17:26.529Z",
"messaging_service_sid": "MGxxx",
"account_sid": "ACxxx",
"user_agent": "some_user_agent"

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

event_typeThe type of event. The value is always click for click events.
sms_sidThe SID of the Message resource that contained the shortened link.
toThe To value of the original Message resource. This is the recipients phone number or channel address (e.g. whatsapp:+15558887474)
fromThe From number of the Message. This is a phone number or channel address from your Messaging Service's sender pool.
linkThe original long link. This shortened link redirected to this link.
click_timeThe ISO 8601(link takes you to an external page) timestamp of when the customer clicked on the shortened link.
messaging_service_sidThe SID of the Messaging Service that sent the Message.
account_sidThe SID of the Twilio Account that sent the Message.
user_agentThe 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.

Messaging records and click events

messaging-records-and-click-events page anchor

If you've configured a custom retention period for your Messaging records(link takes you to an external page), 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(link takes you to an external page) and go to Develop > Messaging > Settings > General > Message Records Data Access and Backup.

Account-based rate limits

account-based-rate-limits page anchor

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.

Rate this page: