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

Link Shortening Onboarding Guide



Prerequisites

prerequisites page anchor
  • 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

generate-a-transport-layer-security-tls-certificate page anchor
  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

update-your-domains-dns-records page anchor
  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
(information)

Info

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

configure-your-messaging-service page anchor

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.

(information)

Info

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.
associate-a-messaging-service-with-your-link-shortening-domain page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.messaging.v1
_11
.linkshorteningMessagingService('DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', 'MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.create()
_11
.then(linkshortening_messaging_service => console.log(linkshortening_messaging_service.domainSid));

Output

_10
{
_10
"domain_sid": "DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/MessagingServices/MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_10
}


Provide your TLS certificate and private key to Twilio

provide-your-tls-certificate-and-private-key-to-twilio page anchor

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.
(information)

Info

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.

(warning)

Warning

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.

uploadupdate-tls-certificate-and-private-key-for-a-link-shortening-domain page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_63
// Download the helper library from https://www.twilio.com/docs/node/install
_63
// Find your Account SID and Auth Token at twilio.com/console
_63
// and set the environment variables. See http://twil.io/secure
_63
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_63
const authToken = process.env.TWILIO_AUTH_TOKEN;
_63
const client = require('twilio')(accountSid, authToken);
_63
_63
const certAndPrivateKey = `-----BEGIN CERTIFICATE-----
_63
MIIDqDCCApACCQCBT5e22Q01fjANBgkqhkiG9w0BAQsFADCBlTELMAkGA1UEBhMC
_63
VVMxCzAJBgNVBAgMAkNBMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMRYwFAYDVQQK
_63
DA1FeGFtcGxlLCBJbmMuMRIwEAYDVQQLDAlUZXN0IERlcHQxFDASBgNVBAMMC2V4
_63
YW1wbGUuY29tMR8wHQYJKoZIhvcNAQkBFhB0ZXN0QGV4YW1wbGUuY29tMB4XDTIz
_63
MDcyNjIwMjUwMVoXDTI0MDcyNTIwMjUwMVowgZUxCzAJBgNVBAYTAlVTMQswCQYD
_63
VQQIDAJDQTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzEWMBQGA1UECgwNRXhhbXBs
_63
ZSwgSW5jLjESMBAGA1UECwwJVGVzdCBEZXB0MRQwEgYDVQQDDAtleGFtcGxlLmNv
_63
bTEfMB0GCSqGSIb3DQEJARYQdGVzdEBleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN
_63
AQEBBQADggEPADCCAQoCggEBAL+uk4TT+7npoMgnah59ZYu4VzM+PInRVbsvYa4S
_63
EfX+GzNy03VmVCsxnM2OxRQjqBxa5nKtRocRbFNk46xpB5fuOcJ6pKwWKo9equ6x
_63
RuZzbo8HkfmrP5a2GcA/Z+ncwjiyKbi7UefwGxaayGPiTFMEZIYVUHE6GDsRKYeJ
_63
nbylpzOtQMJqtRZitkC8BIDh52dZIi/GDPqB6fw4Cubpld9c5qNX575FuF0HUj5B
_63
lc0e4b7EihlNGu4mDUo8FJoHkVqVTFM6KtwhL9A5xdVjZ9XukX0uiaaI+LwzBKJs
_63
Y0zCt99hFp+dMwEc7wL7ECsXSFuH4RAnJn/QglYT9b1uO0MCAwEAATANBgkqhkiG
_63
9w0BAQsFAAOCAQEAHtUqqlWJ74LCFwVup2n0pUoIkHhUJdAv1lvSpyvA7sW/fKCU
_63
RhblmkqMy8i96xZGizuT86nUdf2XcufJhPFee7UopfZE4Ncya4te+7y/S17HM0uk
_63
LMEO1njLhzX+MDuLZOPPXw70JxN1oqxvyZKxrbvaOJ0O4duiEUOfKu//EYY0AdTl
_63
xCkHItiKEsmxjUPjroMd0APJp5aTPUS2c4moB9xjieft2uIG/7d/3gQfswnxJZcd
_63
EzQKclW4U28U1NVtcFhaNwEBC1H0TvBTp/8asl2aTOUP97wcLHPI9qzZWfAzizOU
_63
17S7MxNzjtt4i4/PQ7koIsq31wgmh2jDjh6mMw==
_63
-----END CERTIFICATE-----
_63
-----BEGIN PRIVATE KEY-----
_63
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQC/rpOE0/u56aDI
_63
J2oefWWLuFczPjyJ0VW7L2GuEhH1/hszctN1ZlQrMZzNjsUUI6gcWuZyrUaHEWxT
_63
ZOOsaQeX7jnCeqSsFiqPXqrusUbmc26PB5H5qz+WthnAP2fp3MI4sim4u1Hn8BsW
_63
mshj4kxTBGSGFVBxOhg7ESmHiZ28paczrUDCarUWYrZAvASA4ednWSIvxgz6gen8
_63
OArm6ZXfXOajV+e+RbhdB1I+QZXNHuG+xIoZTRruJg1KPBSaB5FalUxTOircIS/Q
_63
OcXVY2fV7pF9LommiPi8MwSibGNMwrffYRafnTMBHO8C+xArF0hbh+EQJyZ/0IJW
_63
E/W9bjtDAgMBAAECggEAEoOQKBI5jBluuCZmb495EWe6tG5cdotLlorbCm8gYPws
_63
MGn01rANjSZ7mLcjffB7ulFlVMo7t6wNJHjoLKzwWNJfrdMeuKhjb/ma1Pc2e+fG
_63
U/ZNOSo7OBlan2EAbmwuLj+3G+qr3JUqaKKGnG8tJA+WjgTdAjK0SHA97KN0ItZK
_63
ZrZLEdrDTH+jCLl7eGzbAa7cMd24LyE9/Sz0IwJ+E2A2qoyBPGP8kRIByUH8pf94
_63
HnF7DzGBaV7UAC7xuzHPiV0vV+YNjvk236IbDCkGW5Y/j92KxmZKY1lIz/cDCNRD
_63
rAwZtRruIjNtgP9dNq44OQvjAvaFQIS+TMqJpqT3oQKBgQDftE5z/Hm/UyOyoh24
_63
GccisB37eDzDO7/rJq4l3/UvAu566xmI8W3ToQMaDbtOfGOoLKH3mPY8c+yYJrCt
_63
HM2uzxnFxPkfZ4I8JoplJ3pkNinYdX81jmmeO3gk6uzAgZOtSHSMP7TWkrTct/vf
_63
ZduvzlrGKtcbzfPuFdBABQeeaQKBgQDbWshIRzOkqku7X/4jj0qDa4dExtOzLzXw
_63
VsEV9sCXemMtFYmFWJAHeNvnfxKeBjtXa7skEQTojXcd/DJF1eTtLJNbpJpIUfiU
_63
BdqfmMvf7eDnsiUmzRlqxnc/bwhzzl3ac1gL0n7WXBA+HYEp5LhIlhGuzKlpIET3
_63
1sHKim7uywKBgQCyudOURzrd6Qa0SWGFHNNEm4DY0I97S9lhfl3UVMIG9UijXAHi
_63
r0EXu6RGxIHJiwfz7PTaZJMWaWe1h/PP2xtZdo0YvO5scL5UYFZhytC2D7APCJDB
_63
sS4hBVJP7IGKq/vYjfLPunY4mK13SmcpbK/AHhXYDZIe3MTuiu7+twYHQQKBgQDX
_63
4IZPq9NFcVvK8nP4pyLcJ80egNcD96iL+bVZWli8O3SzgAixtTE6SVWShNrbrqJk
_63
LOAmZKGCBQd/+R244QLF8CKuBFbaaeHMO96nRwcOQNwg6o/pmdwz21KsmSemYSi4
_63
vt+d8vFlIYHSv9LIWhKLTTXl5AGuNlXp2+8o2AjI9QKBgQDXQzJWmiVmTsBYOTWD
_63
YTp2o4Tn0HlLk3KHaBKHGiO0YGVuhXa2jz0u3jg5LLG7vusOZhQBkd4tN7L10ZMM
_63
l5jSr8uncW4/3gZ/O/URQZcMH+Uzttw8nVL3mzLS/M600I+ryZdLkrmtDQWUBRwj
_63
fRre92n5B+9AgpEl6RyegsXToA==
_63
-----END PRIVATE KEY-----`
_63
_63
client.messaging.v1.domainCerts('DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_63
.update({
_63
tlsCert: certAndPrivateKey
_63
})
_63
.then(domain_certs => console.log(domain_certs.domainName));

Output

_13
{
_13
"certificate_sid": "CWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"domain_name": "https://www.example.com",
_13
"domain_sid": "DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"date_expires": "2021-02-06T18:02:04Z",
_13
"date_created": "2021-02-06T18:02:04Z",
_13
"date_updated": "2021-02-06T18:02:04Z",
_13
"url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Certificate",
_13
"cert_in_validation": {
_13
"date_expires": "2021-02-06T18:02:04Z",
_13
"status": "pending"
_13
}
_13
}

  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.

check-your-link-shortening-domains-certificate-validation-status page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messaging.v1.domainCerts('DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(domain_certs => console.log(domain_certs.domainName));

Output

_13
{
_13
"certificate_sid": "CWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"domain_name": "https://api.example.com",
_13
"domain_sid": "DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_13
"date_expires": "2021-02-06T18:02:04Z",
_13
"date_created": "2021-02-06T18:02:04Z",
_13
"date_updated": "2021-02-06T18:02:04Z",
_13
"url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Certificate",
_13
"cert_in_validation": {
_13
"date_expires": "2021-02-06T18:02:04Z",
_13
"status": "pending"
_13
}
_13
}


Configure your domain's default behavior

configure-your-domains-default-behavior page anchor

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 settingDescription
Fallback URLThe URL to which Twilio redirects recipients after a shortened link has expired.
Callback URLThe 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(link takes you to an external page), which may incur higher costs.

Note: This setting only affects Messages with a ShortenUrls parameter set to true.
Disable HTTPSWhether 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.

(information)

Info

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.

Configure your domain's default behavior

configure-your-domains-default-behavior-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.messaging.v1.domainConfig('DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.update({
_15
continueOnFailure: true,
_15
disableHttps: true,
_15
fallbackUrl: 'https://example.com/',
_15
callbackUrl: 'https://example.com/my-click-event-callback-endpoint'
_15
})
_15
.then(domain_config => console.log(domain_config.domainSid));

Output

_11
{
_11
"domain_sid": "DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_11
"config_sid": "ZKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_11
"fallback_url": "https://example.com/",
_11
"callback_url": "https://example.com/my-click-event-callback-endpoint",
_11
"continue_on_failure": true,
_11
"date_created": "2015-07-30T20:00:00Z",
_11
"date_updated": "2015-07-30T20:00:00Z",
_11
"url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Config",
_11
"disable_https": true
_11
}



Rate this page: