How to Configure Link Shortening

Link Shortening is a feature of Messaging Services that allows you to shorten URLs in your messages and track clicks. This topic explains how you can configure Link Shortening using the Domain Certificate API and Domain Config API.

You can also configure Link Shortening & Click Tracking using the Twilio Console. Navigate to Messaging > Services and select the Messaging Service you want to use. In the left navigation pane, click on Link Shortening and follow the steps for setup.

To create a message with shortened links via Twilio Messaging API, navigate here.

Step 1: Setting up an Organization

Link Shortening requires you to set up an Organization in the Twilio Admin Center. This can be accessed and set up via the console. More information regarding Organizations can be found here.

Step 2: Registering Domains

After setting up your Organization, you can now register and verify domains within the Organization. You will need to already own the domains you wish to register and will need to be able to update your DNS configurations or upload an HTML page file to your website’s root directory to verify the domains. Link Shortening can only be used with verified domains. More information regarding domains in Organizations can be found here.

Step 3: Adding DNS Records

Domain Name System (DNS) records are configurable records for your domain that contains information such as what IP addresses are associated with the domain and how to handle requests to that domain.

The root domain is the highest hierarchical level in the domain (e.g. twilio.com). Subdomains are at levels lower than your root domain (e.g. abc.twilio.com, def.twilio.com, ghi.twilio.com).

Domains or subdomains set up for Link Shortening purposes have to be exclusive for Twilio Link Shortening only and the DNS records must satisfy the following condition. If you want to onboard a root domain, you will need to point the A record of the domain to these 3 IPs and these IPs only. If other IPs are included, we will not be able to redirect to the destination URL.

3.233.187.46
3.233.108.250
54.157.2.211

If you are onboarding a subdomain, you will need to point the CNAME record of the subdomain to the following:

lsct.ashburn.us1.twilio.com

Step 4: Generating a TLS Certificate

The TLS certificate and private key must be generated in a PEM format (for the specific subdomain if relevant).

We only support private keys that start with BEGIN PRIVATE KEY or PKCS #8 formatted keys.

We do not support Subject Alternative Names in TLS Certificates.

You must generate a TLS certificate and private key to prove ownership of the domain you intend to use. Twilio requires that all redirects be served over HTTPS. Since Twilio will serve the redirects for a domain that you own, you'll need to provide TLS certificates to Twilio, so that a trusted connection can be set up with the requesting clients (consumers' browsers) and Twilio's servers on your behalf.

Please follow the steps below to upload your certificate. Most domain hosting services offer managed certificate solutions. There are paid options with annual subscriptions and free options such as letsencrypt.org (with the caveat that most free options only provide an expiration of up to 3 months).

Please note: It is your responsibility to track certificate expiration dates and re-upload certificates in order to continue using the Link Shortening feature. Without a valid TLS certificate for a domain, Link Shortening will cease to work and your messages will be delivered with original long links that may result in multiple message segments and broken links. You can set up alerts with email notifications to get notified when your TLS certificate is about to expire with Twilio Alarms. The error code 30131 indicates a soon-to-be-expired TLS certificate.

Step 5: Uploading TLS Certificate

You can upload the TLS certificate and private key and configure Link Shortening & Click Tracking using the Twilio Console. Navigate to Messaging > Services and select the Messaging Service you want to use. In the left navigation pane, click on Link Shortening and follow the steps for setup.

Once your private key is verified, use your DomainSid to upload your TLS certificate and private key.

The following is an example of the correct formatting for the TLS certificate and private key:

Sample Request:

curl -X POST https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/Certificate \
--data-urlencode "TlsCert=$tlsCert" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Once you upload the TLS certificate, you may see that the validated field is returning false. It takes at most 5 minutes for the TLS certificate to be validated. You can check the status of the validation using the Domain Certificates API.

Your links will not be shortened if the TLS certificate is not validated.

Step 6: Setting Up Domain Configurations

After you have uploaded a TLS certificate along with the private key for the domain you wish to use, you can now set default configurations for the domain and assign the configuration to Messaging Services. The following are the fields included in the Domain Config API. After you set default configurations for the domain, Twilio will automatically apply the default domain, fallback URL, callback URL, delivery preference, and HTTPS prefix preference whenever you send a message with long links through the associated Messaging Service.

Field	Required	Description
Domain	Yes	Domain you wish to use when shortening long links. You will need to register, verify, and upload a TLS certificate for the domain during onboarding.
Fallback URL	No	Shortened links will expire after 90 days and we will no longer redirect recipients to the original long link. We will redirect the recipients to the fallback URL after the shortened links are expired.
Callback URL	No	If you wish to receive click events to your webhook whenever the recipients click on the shortened links, you can set a callback URL.
Delivery Preference	No	In case of Link Shortening outage, you can choose whether to send the message with the original links (`continue_on_failure=true`) or stop the message from being delivered (`continue_on_failure=false`). By default, Link Shortening will stop the delivery for exceeding account limits but continue the delivery for any other service outages.
HTTPS Prefix Preference	No	You can choose to remove HTTPS prefix from the shortened link with `disable_https` parameter. If it's set to true, the shortened link will be `example.com/he4jRhU3r9`. If it's set to false, the shortened link will be `https://example.com/he4jRhU3r9`. This preference is cached for 15 minutes if the preference has been updated less than a day, and 3 hours if the preference has been updated greater than a day.

Setting Default Configurations for a Domain

curl -X POST 
https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/Config \
--data-urlencode "FallbackUrl=$FALLBACK_URL" \
--data-urlencode "CallbackUrl=$CALLBACK_URL" \
--data-urlencode "ContinueOnFailure=true" \
--data-urlencode "DisableHttps=false" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Associating a Domain Configuration to a Messaging Service

Domain configuration can be associated with multiple Messaging Services so that the same domain, callback URL, and fallback URL are applied.

curl -X POST https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/MessagingServices/$MESSAGING_SERVICE_SID \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Disassociating a Domain Configuration from a Messaging Service

Disassociating a domain configuration from a Messaging Service will essentially disable Link Shortening and Click Tracking for that particular Messaging Service. Since there is no domain configuration set, even if you send the message with ShortenUrls=true parameter with the Messaging Service, the original links in the message body will not be shortened.

curl -X DELETE https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/MessagingServices/$MESSAGING_SERVICE_SID \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Updating Fields of Existing Domain Configuration

You can always update the callback URL, fallback URL, delivery preference, and/or HTTPS prefix preference for a particular domain configuration.

curl -X POST 
https://messaging.twilio.com/v1/LinkShortening/Domains/$DOMAIN_SID/Config \
--data-urlencode "FallbackUrl=$FALLBACK_URL" \
--data-urlencode "CallbackUrl=$CALLBACK_URL" \
--data-urlencode "ContinueOnFailure=true" \
--data-urlencode "DisableHttps=false" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Link Clicked Event Payload Response

{
  "event_type": "click",
  "sms_sid": "SMxxx",
  "to": "+11234567890",
  "from": "+10987654321",
  "link": "https://www.longlink.com/original_link",
  "click_time": "2022-10-24T17:17:26.529Z",
  "messaging_service_sid": "MGxxx",
  "account_sid": "ACxxx",
  "user_agent": "some_user_agent"
}

FAQs and Troubleshooting

If you encounter issues with Link Shortening, we've provided the following diagnostics tips to help get you back on track.

Does Link Shortening work with Message Scheduling?
Yes, you can use Message Scheduling with Link Shortening. You will need to have configured Link Shortening with the domain you wish to use before you can schedule the messages with shortened links. Please note that while Link Shortening is in Public Beta, there is an account based rate limit of 100 requests per second. If you plan to schedule messages at scale, you may exceed the rate limit for Link Shortening and your messages will fail to be delivered at scheduled time. If you wish to increase your account rate limit to a higher custom rate limit, please reach out to support@twilio.com.
Can I increase the account based rate limit for my account?
While in Public Beta, Link Shortening has 100 requests per second account based rate limit. If you wish to increase your account rate limit to a higher custom rate limit, please reach out to support@twilio.com.
I am getting a "Certificate's domain name does not match the registered domain" error and cannot upload my certificate and private key. Twilio Link Shortening requires a TLS certificate and private key that is specifically for the domain you have registered with Twilio. You can check the domain name of the certificate using tools such as OpenSSL or other certificate management tools. Please make sure that the domain name matches the domain you registered exactly.
I am getting an "Invalid certificate an/or private key" error and cannot upload my certificate and private key. Please make sure that you are uploading the full value of the certificate and private key beginning with "-----BEGIN CERTIFICATE-----" and ending with "-----END CERTIFICATE-----" for certificates and "-----BEGIN PRIVATE KEY-----" and "-----END PRIVATE KEY-----" for private keys. There cannot be extra newline characters before and after the values and the header/footer must exactly match in order for them to be accepted.
My private key does not start with "-----BEGIN PRIVATE KEY-----".
Often, third party vendors export different formats of private keys. Twilio Link shortening accepts PKCS #8 private keys so if your key does not start with "-----BEGIN PRIVATE KEY-----", you will need to convert the key using OpenSSL or export the private key again with the proper format specified.
Can I use the same domain for multiple Messaging Services? Yes, you can use the same domain for multiple Messaging Services. The same domain configuration will be applied such as callback URL and fallback URL for the domain. You cannot customize callback URL and fallback URL for the same domain and if you do change for one Messaging Service, that change will be applied to all other Messaging Services that are using the same domain. Domain configuration fields such as callback URL and fallback URL are tied to the domain and that configuration is applied to multiple Messaging Services. You will only need to upload a certificate and private key once for a single domain, so you will not need to upload again if you choose to use the same domain across multiple Messaging Services.
Can I use the same domain for multiple Twilio accounts? Yes, you will need to make sure all of the accounts you wish to use are under the same Organization. A domain resource is a resource under the Organization, so any accounts under the same Organization will be able to use the domain in any of those accounts. You will be able to select the domain under Messaging > Services > Link Shortening. You will only need to upload the certificate and private key once for the domain, which means you do not need to upload again within individual accounts.
How can I be notified when my certificate is about to expire? It is your responsibility to track certificate expiration dates and re-upload certificates in order to continue using the Link Shortening feature. Without a valid TLS certificate for a domain, Link Shortening will cease to work and your messages will be delivered with original long links that may result in multiple message segments and broken links. You can set up alerts with email notifications to get notified when your TLS certificate is about to expire with Twilio Alarms. The error code 30131 indicates a soon-to-be-expired TLS certificate.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Need some help?

Thank you for your feedback!

Thanks for your feedback!