Programmable Messaging

Twilio

Menu

Link Shortening Onboarding Guide

The Link Shortening feature is only available for use with Messaging Services and is currently in Public Beta.

Prerequisites

  • You need to own a domain or subdomain that is only used for Link Shortening with Twilio.
    • You must be able to verify the domain with Twilio. This requires changing the Domain Name System (DNS) records or uploading an HTML file to the root directory of the domain.
  • You need to have a Twilio Organization.
  • You need to add your domain to the Organization and verify the domain with Twilio.
  • The Twilio Account(s) you wish to use with Link Shortening must be added to the Organization.

The Account(s) must have a Messaging Service with at least one sender.

Generate a Transport Layer Security (TLS) certificate

  1. Generate a TLS certificate and private key for your Link Shortening domain.

    • With Link Shortening, Twilio serves redirects for your domain. A TLS certificate allows Twilio to establish an encrypted connection between a customer's browser and Twilio's servers on your behalf (redirects are served over HTTPS).

    • 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).

    • Keep the following in mind when generating your certificate and key:

      • The TLS certificate and private key must be generated in a PEM format.
      • If you're using a subdomain, the certificate and key must be generated for the subdomain.
      • Subject Alternative Names in TLS Certificates are now supported.
      • Wildcard certificates for subdomains are now supported.
      • Certificates must start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----
      • Private keys must start with -----BEGIN PRIVATE KEY----- and end with -----END PRIVATE KEY----- or be in PKCS #8 format.

    • If your private key is not provided in the correct format, convert the key to PKCS #8 format using OpenSSL or export the private key again with the proper format specified.

    • 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 need to convert the key using OpenSSL or export the private key again with the proper format specified.

  2. Make note of the certificate's expiration date.

    • It is your responsibility to track certificate expiration dates. Link Shortening does not work without valid TLS certificates; your customers may receive broken links and your Account may be charged for additional message segments due to long URLs.

    • You can use Twilio Alarms to set up email notifications for the 30131 warning code, which indicates that a certificate is about to expire.

Update your domain's DNS records

  1. Open a new browser tab or window and navigate to your domain's configuration page.
    • If you're using a root domain (e.g. example.com), find the DNS record configuration.
    • If you're using a subdomain (e.g. link.example.com), find the subdomain's CNAME record configuration.

  2. If you're using a root domain, point the A record of the domain to the following 3 IP addresses only. If other IPs are included, Link Shortening does not work.

    • 3.233.187.46
    • 3.233.108.250
    • 54.157.2.211

    If you're using a subdomain, point the CNAME record of the subdomain to the following:

    • lsct.ashburn.us1.twilio.com

The rest of the onboarding steps for Link Shortening can be completed either in the Console or via REST API.

If you're an ISV with many domains and/or Messaging Services that you need to configure, you should use the REST API. Other customers should use the Console.

Regardless of the strategy you choose, you should read the rest of the information on this page.

Configure your Messaging Service

This section covers how to associate your Messaging Service with your Link Shortening domain.

A Link Shortening domain can be used with multiple Messaging Services, as long as the Messaging Services all belong to an Account within your Twilio Organization.

If you want to set up Link Shortening for another Messaging Service, repeat the steps in this section.

If you're using the Console, follow the Console steps below. If you're using the REST API, use the API steps below.

Console

  1. In a new tab, open your Console and navigate to Messaging > Messaging Services.
  2. Select the Messaging Service that you want to configure.
  3. In the left hand navigation pane, select Link Shortening.
  4. In the Organization and domain section, in the Domain field, select your link shortening domain from the dropdown.
  5. Click Save changes.
  6. Go to the "Provide your TLS certificate and private key to Twilio" section below.

API

  1. Go to the Admin Center of the Console. Navigate to Domains and select on your domain. The SID is on the Domain details page under Domain Sid. Save this SID because you'll need it in future steps.
  2. Next, you need your Messaging Service's SID. To find it, in the Console, navigate to Messaging > Messaging Services. Select the Messaging Service that you want to configure. Save this SID because you'll need it in future steps.
  3. Send a POST request to the Link Shortening domain's Messaging Services subresource. Place your domain's SID and Messaging Service SID in the URL. An example request is shown below.

Provide your TLS certificate and private key to Twilio

This section describes how to upload your TLS certificate and private key to Twilio.

Keep the following in mind as you complete this section:

  • Make sure your certificate and private key are in the correct format as described in the "Generate a TLS certificate" section above.
  • The domain is associated with your Twilio Organization, so you only need to upload your certificate once, even if multiple Accounts within the Organization use the domain.

When your certificate is about to expire, repeat the steps in this section to upload a new certificate.

If you're using the Console, follow the Console steps below. If you're using the REST API, use the API steps below.

Console

  1. Under Upload certificate, click Upload new certificate.
  2. Read the information in the pop-up and click the Continue button.
  3. In the Upload TLS certificate and private key pop-up, paste your TLS certificate into the TLS certificate input box.
    • The TLS Certificate's first line must be -----BEGIN CERTIFICATE-----
    • The last line must be -----END CERTIFICATE-----
    • Make sure there are no extra newline characters at the beginning or end of the certificate. Example:
  4. Paste your private key into the Private key input box.
    • The private key's first line must be -----BEGIN PRIVATE KEY-----
    • The private key's last line must be -----END PRIVATE KEY-----
    • Make sure there are no extra newline characters at the beginning or end of the private key. Example:
  5. Click the Upload button. It takes up to five minutes to validate the certificate and key. Check the status by checking the Cert status under Current certificate details. If you encounter an error at this step, make sure your certificate and private key are in the correct format as described in the "Generate a TLS certificate" section above.
  6. Go to the "Configure your domain's default behavior" section below.

API

  1. Send a POST request to your Link Shortening domain's Certificate subresource.

    In the request, the TlsCert parameter's value must be the concatenated certificate and private key. The proper format of the TlsCert value is shown in the example below.

    It can take up to five minutes to validate a certificate. Because of this, Twilio's response to this POST request may contain a cert_in_validation.status property with a value of pending.

    Use the request in Step 2 (below) to check the certificate's validation status.

Don't hard-code or save your certificate/key anywhere that might be pushed into version control. If using a Helper Library, use environment variables. The certificate/key is saved as a variable for illustration purposes only.

  1. Check the domain's certificate validation by sending a GET request to your Link Shortening domain's Certificate subresource. An example request is shown below.

    If the certificate's validation is still pending, Twilio's response to this GET request contains a cert_in_validation.status property with a value of pending.

    Once the certificate has been validated, Twilio's response to this GET request contains a cert_in_validation property with a value of null.

Configure your domain’s default behavior

This section covers how to configure your Link Shortening domain's default behavior.

The table below describes the domain default settings that can be configured.

Domain default setting Description
Fallback URL The URL to which Twilio redirects recipients after a shortened link has expired.
Callback URL The URL to which Twilio sends click event data. Twilio sends a request to the Callback URL after a recipient clicks on a shortened link.

Deliver messages anyway in case of Link Shortening failure (Console)

ContinueOnFailure (API)

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 (default value is true). This may result in multiple message segments, which may incur higher costs.

Note: This setting only affects Messages with a ShortenUrls parameter set to true.
Disable HTTPS

Whether or not Twilio removes the https:// prefix from shortened links.

If true, shortened links do not have the https:// prefix (e.g., twil.io/j9kj9K3huK9u7).

If set to false, shortened links have the https:// prefix (e.g., https://twil.io/j9kj9K3huK9u7).

Default value is false.

Please note, it takes up to 15 minutes for the change to be applied.

Link Shortening domain default configurations are associated with the domain rather than a Messaging Service. This means that you can update the domain defaults and the changes apply to all Messaging Services that use the Link Shortening domain.

In the future, if you want to change a Link Shortening domain's default configuration, repeat the steps in this section.

If you're using the Console, follow the Console steps below. If you're using the REST API, use the API steps below.

Console

  1. In the Domain configuration section, fill in the following fields:

    • Domain fallback URL
    • Click tracking callback URL

  2. Select or deselect the checkboxes for the following fields:

    • Disable "https://" prefix
    • Deliver messages anyway in case of Link Shortening failure

  3. Click the Save button.

  4. Go to the "Next Steps" section below.

API

  1. Send a POST request to the Link Shortening domain's Config subresource with the following parameters:

    • FallbackUrl
    • CallbackUrl
    • ContinueOnFailure
    • DisableHttps

    A sample request is shown below.

Loading Code Sample...
 
        

        


        

        


        


        

        

        

        

        

        

        

        

        

        

        
          Configure your domain's default behavior
        
        

        

        

        

        

        

        

        Next steps
        


         
        

        

        

        

        
Rate this page:

        











        

        

        

        

        

        

        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.
  
        

        


        


        

        

        

        

        

        






        Thank you for your feedback!
        

        
  Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        









        

        

        



        

        



        

        



        

        



        

        



        

        

        

        



        

        



        

        

        



        

        



        

        

        
Need help? Talk to Support

        

        

        
            Protected by reCAPTCHA – PrivacyTerms

        

        

        

        

        

        

        

        


        
          Sending your feedback...
        
        

        

        

        

        

        
      🎉 Thank you for your feedback!
    
        

        

        

        
      Something went wrong. Please try again.
    
        

        

        

        






        Thanks for your feedback!
        

        
thanks-feedback-gif