The Account(s) must have a Messaging Service with at least one sender.
Generate a TLS certificate and private key for your Link Shortening domain.
Keep the following in mind when generating your certificate and key:
-----BEGIN CERTIFICATE-----
and end with -----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
and end with -----END PRIVATE KEY-----
or be in PKCS #8 format.
-----BEGIN PRIVATE KEY-----
, you need to convert the key using OpenSSL or export the private key again with the proper format specified.
Make note of the certificate's expiration date.
Open a new browser tab or window and navigate to your domain's configuration page.
example.com
), find the DNS record configuration.
link.example.com
), find the subdomain's CNAME record configuration.
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.
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
API
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.
This section describes how to upload your TLS certificate and private key to Twilio.
Keep the following in mind as you complete this section:
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
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----
API
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.
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
.
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
In the Domain configuration section, fill in the following fields:
Select or deselect the checkboxes for the following fields:
API
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.