Link Shortening Onboarding Guide

• 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 Twilio Account(s) must have a Messaging Service with at least one sender.

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'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.

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.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createLinkshorteningMessagingService() {
11
  const linkshorteningMessagingService = await client.messaging.v1
12
    .linkshorteningMessagingService(
13
      "DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14
      "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
15
    )
16
    .create();
17

18
  console.log(linkshorteningMessagingService.domainSid);
19
}
20

21
createLinkshorteningMessagingService();

1
{
2
  "domain_sid": "DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4
  "url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/MessagingServices/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
5
}

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

3. Click 'Validate' to validate your DNS settings.

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). We offer two options for setting up TLS certificates for your Link Shortening domain: Twilio-managed Certificates (preferred) and Bring Your Own Certificate.

Keep the following in mind as you complete this section:

• Your domain is associated with your Twilio Organization, so you only need to generate or upload your certificate once, even if multiple Accounts within the Organization use the same domain.

Option 1 (Preferred) - Twilio-managed Certificate: Use our new Certificate Manager feature to entrust Twilio with handling certificate requests and renewals. This is the preferred option.

Console

1. Choose Twilio-managed certificate as the certificate management option.
2. Click Continue in the modal pop up and wait for the certificate to be processed. This may take a few minutes.
3. Your new certificate details will be displayed under the Certificate management tab. You may need to refresh your page if you still see the processing message.

API

Send a POST request to the Link Shortening RequestManagedCert subresource, placing your domain's SID in the URL.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updateRequestManagedCert() {
11
  const requestManagedCert = await client.messaging.v1
12
    .requestManagedCert("DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .update();
14

15
  console.log(requestManagedCert.domainSid);
16
}
17

18
updateRequestManagedCert();

1
{
2
  "certificate_sid": "CWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "domain_name": "https://api.example.com",
4
  "domain_sid": "DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
5
  "date_created": "2021-02-06T18:02:04Z",
6
  "date_updated": "2021-02-06T18:02:04Z",
7
  "date_expires": "2021-02-06T18:02:04Z",
8
  "url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RequestManagedCert",
9
  "managed": true,
10
  "requesting": true
11
}

Option 2 - Bring Your Own 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).

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

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

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 Continue.

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 Upload. 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 previous step.

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.

   Upload/update TLS Certificate and Private Key for a Link Shortening domain

   Copy code block

   1
   // Download the helper library from https://www.twilio.com/docs/node/install
   2
   // Find your Account SID and Auth Token at twilio.com/console
   3
   // and set the environment variables. See http://twil.io/secure
   4
   const accountSid = process.env.TWILIO_ACCOUNT_SID;
   5
   const authToken = process.env.TWILIO_AUTH_TOKEN;
   6
   const client = require('twilio')(accountSid, authToken);
   7
   
   8
   const certAndPrivateKey = `-----BEGIN CERTIFICATE-----
   9
   MIIDqDCCApACCQCBT5e22Q01fjANBgkqhkiG9w0BAQsFADCBlTELMAkGA1UEBhMC
   10
   VVMxCzAJBgNVBAgMAkNBMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMRYwFAYDVQQK
   11
   DA1FeGFtcGxlLCBJbmMuMRIwEAYDVQQLDAlUZXN0IERlcHQxFDASBgNVBAMMC2V4
   12
   YW1wbGUuY29tMR8wHQYJKoZIhvcNAQkBFhB0ZXN0QGV4YW1wbGUuY29tMB4XDTIz
   13
   MDcyNjIwMjUwMVoXDTI0MDcyNTIwMjUwMVowgZUxCzAJBgNVBAYTAlVTMQswCQYD
   14
   VQQIDAJDQTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzEWMBQGA1UECgwNRXhhbXBs
   15
   ZSwgSW5jLjESMBAGA1UECwwJVGVzdCBEZXB0MRQwEgYDVQQDDAtleGFtcGxlLmNv
   16
   bTEfMB0GCSqGSIb3DQEJARYQdGVzdEBleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN
   17
   AQEBBQADggEPADCCAQoCggEBAL+uk4TT+7npoMgnah59ZYu4VzM+PInRVbsvYa4S
   18
   EfX+GzNy03VmVCsxnM2OxRQjqBxa5nKtRocRbFNk46xpB5fuOcJ6pKwWKo9equ6x
   19
   RuZzbo8HkfmrP5a2GcA/Z+ncwjiyKbi7UefwGxaayGPiTFMEZIYVUHE6GDsRKYeJ
   20
   nbylpzOtQMJqtRZitkC8BIDh52dZIi/GDPqB6fw4Cubpld9c5qNX575FuF0HUj5B
   21
   lc0e4b7EihlNGu4mDUo8FJoHkVqVTFM6KtwhL9A5xdVjZ9XukX0uiaaI+LwzBKJs
   22
   Y0zCt99hFp+dMwEc7wL7ECsXSFuH4RAnJn/QglYT9b1uO0MCAwEAATANBgkqhkiG
   23
   9w0BAQsFAAOCAQEAHtUqqlWJ74LCFwVup2n0pUoIkHhUJdAv1lvSpyvA7sW/fKCU
   24
   RhblmkqMy8i96xZGizuT86nUdf2XcufJhPFee7UopfZE4Ncya4te+7y/S17HM0uk
   25
   LMEO1njLhzX+MDuLZOPPXw70JxN1oqxvyZKxrbvaOJ0O4duiEUOfKu//EYY0AdTl
   26
   xCkHItiKEsmxjUPjroMd0APJp5aTPUS2c4moB9xjieft2uIG/7d/3gQfswnxJZcd
   27
   EzQKclW4U28U1NVtcFhaNwEBC1H0TvBTp/8asl2aTOUP97wcLHPI9qzZWfAzizOU
   28
   17S7MxNzjtt4i4/PQ7koIsq31wgmh2jDjh6mMw==
   29
   -----END CERTIFICATE-----
   30
   -----BEGIN PRIVATE KEY-----
   31
   MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQC/rpOE0/u56aDI
   32
   J2oefWWLuFczPjyJ0VW7L2GuEhH1/hszctN1ZlQrMZzNjsUUI6gcWuZyrUaHEWxT
   33
   ZOOsaQeX7jnCeqSsFiqPXqrusUbmc26PB5H5qz+WthnAP2fp3MI4sim4u1Hn8BsW
   34
   mshj4kxTBGSGFVBxOhg7ESmHiZ28paczrUDCarUWYrZAvASA4ednWSIvxgz6gen8
   35
   OArm6ZXfXOajV+e+RbhdB1I+QZXNHuG+xIoZTRruJg1KPBSaB5FalUxTOircIS/Q
   36
   OcXVY2fV7pF9LommiPi8MwSibGNMwrffYRafnTMBHO8C+xArF0hbh+EQJyZ/0IJW
   37
   E/W9bjtDAgMBAAECggEAEoOQKBI5jBluuCZmb495EWe6tG5cdotLlorbCm8gYPws
   38
   MGn01rANjSZ7mLcjffB7ulFlVMo7t6wNJHjoLKzwWNJfrdMeuKhjb/ma1Pc2e+fG
   39
   U/ZNOSo7OBlan2EAbmwuLj+3G+qr3JUqaKKGnG8tJA+WjgTdAjK0SHA97KN0ItZK
   40
   ZrZLEdrDTH+jCLl7eGzbAa7cMd24LyE9/Sz0IwJ+E2A2qoyBPGP8kRIByUH8pf94
   41
   HnF7DzGBaV7UAC7xuzHPiV0vV+YNjvk236IbDCkGW5Y/j92KxmZKY1lIz/cDCNRD
   42
   rAwZtRruIjNtgP9dNq44OQvjAvaFQIS+TMqJpqT3oQKBgQDftE5z/Hm/UyOyoh24
   43
   GccisB37eDzDO7/rJq4l3/UvAu566xmI8W3ToQMaDbtOfGOoLKH3mPY8c+yYJrCt
   44
   HM2uzxnFxPkfZ4I8JoplJ3pkNinYdX81jmmeO3gk6uzAgZOtSHSMP7TWkrTct/vf
   45
   ZduvzlrGKtcbzfPuFdBABQeeaQKBgQDbWshIRzOkqku7X/4jj0qDa4dExtOzLzXw
   46
   VsEV9sCXemMtFYmFWJAHeNvnfxKeBjtXa7skEQTojXcd/DJF1eTtLJNbpJpIUfiU
   47
   BdqfmMvf7eDnsiUmzRlqxnc/bwhzzl3ac1gL0n7WXBA+HYEp5LhIlhGuzKlpIET3
   48
   1sHKim7uywKBgQCyudOURzrd6Qa0SWGFHNNEm4DY0I97S9lhfl3UVMIG9UijXAHi
   49
   r0EXu6RGxIHJiwfz7PTaZJMWaWe1h/PP2xtZdo0YvO5scL5UYFZhytC2D7APCJDB
   50
   sS4hBVJP7IGKq/vYjfLPunY4mK13SmcpbK/AHhXYDZIe3MTuiu7+twYHQQKBgQDX
   51
   4IZPq9NFcVvK8nP4pyLcJ80egNcD96iL+bVZWli8O3SzgAixtTE6SVWShNrbrqJk
   52
   LOAmZKGCBQd/+R244QLF8CKuBFbaaeHMO96nRwcOQNwg6o/pmdwz21KsmSemYSi4
   53
   vt+d8vFlIYHSv9LIWhKLTTXl5AGuNlXp2+8o2AjI9QKBgQDXQzJWmiVmTsBYOTWD
   54
   YTp2o4Tn0HlLk3KHaBKHGiO0YGVuhXa2jz0u3jg5LLG7vusOZhQBkd4tN7L10ZMM
   55
   l5jSr8uncW4/3gZ/O/URQZcMH+Uzttw8nVL3mzLS/M600I+ryZdLkrmtDQWUBRwj
   56
   fRre92n5B+9AgpEl6RyegsXToA==
   57
   -----END PRIVATE KEY-----`
   58
   
   59
   client.messaging.v1.domainCerts('DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
   60
     .update({
   61
        tlsCert: certAndPrivateKey
   62
      })
   63
     .then(domain_certs => console.log(domain_certs.domainName));

   Output

   Copy output

   1
   {
   2
       "certificate_sid": "CWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   3
       "domain_name": "https://www.example.com",
   4
       "domain_sid": "DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   5
       "date_expires": "2021-02-06T18:02:04Z",
   6
       "date_created": "2021-02-06T18:02:04Z",
   7
       "date_updated": "2021-02-06T18:02:04Z",
   8
       "url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Certificate",
   9
       "cert_in_validation": {
   10
           "date_expires": "2021-02-06T18:02:04Z",
   11
           "status": "pending"
   12
       }
   13
   }

2. 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 domain's certificate validation status

   Copy code block

   1
   // Download the helper library from https://www.twilio.com/docs/node/install
   2
   const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
   3
   
   4
   // Find your Account SID and Auth Token at twilio.com/console
   5
   // and set the environment variables. See http://twil.io/secure
   6
   const accountSid = process.env.TWILIO_ACCOUNT_SID;
   7
   const authToken = process.env.TWILIO_AUTH_TOKEN;
   8
   const client = twilio(accountSid, authToken);
   9
   
   10
   async function fetchDomainCertV4() {
   11
     const domainCert = await client.messaging.v1
   12
       .domainCerts("DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
   13
       .fetch();
   14
   
   15
     console.log(domainCert.domainSid);
   16
   }
   17
   
   18
   fetchDomainCertV4();

   Output

   Copy output

   1
   {
   2
     "certificate_sid": "CWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
   3
     "domain_name": "https://api.example.com",
   4
     "domain_sid": "DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   5
     "date_expires": "2021-02-06T18:02:04Z",
   6
     "date_created": "2021-02-06T18:02:04Z",
   7
     "date_updated": "2021-02-06T18:02:04Z",
   8
     "url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Certificate",
   9
     "cert_in_validation": {
   10
       "date_expires": "2021-02-06T18:02:04Z",
   11
       "status": "pending"
   12
     }
   13
   }

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.

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.

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 Save.

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.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updateDomainConfig() {
11
  const domainConfig = await client.messaging.v1
12
    .domainConfig("DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .update({
14
      callbackUrl: "https://example.com/my-click-event-callback-endpoint",
15
      continueOnFailure: true,
16
      disableHttps: true,
17
      fallbackUrl: "https://example.com/",
18
    });
19

20
  console.log(domainConfig.domainSid);
21
}
22

23
updateDomainConfig();

1
{
2
  "domain_sid": "DNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "config_sid": "ZKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "fallback_url": "https://example.com/",
5
  "callback_url": "https://example.com/my-click-event-callback-endpoint",
6
  "continue_on_failure": true,
7
  "date_created": "2015-07-30T20:00:00Z",
8
  "date_updated": "2015-07-30T20:00:00Z",
9
  "url": "https://messaging.twilio.com/v1/LinkShortening/Domains/DNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Config",
10
  "disable_https": true
11
}

• Send a message with a shortened link

• Check out one of the following Blog posts:

  • How to Schedule and Track Marketing Campaigns

  • Advanced Guide to Link Shortening and Link Tracking with Twilio Messaging

  • Link Shortening and Click Tracking SSL FAQ