> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom URL Shortening with Telnyx Messaging

> Use the Telnyx URL shortening service with custom branded links in SMS to improve open rates and avoid spam filters that block popular shortener domains.

\| [Mission Control Portal](#mission-control-portal) | [cURL](#curl) | [Python](#python) | [Ruby](#ruby) | [Node](#node) | [PHP](#php) | [.NET](#net) |

***

<Callout type="info">
  If you are interested in activating this feature, please reach out to our Sales Team.After this feature is activated for your account, you will be able to configure it following the steps below.
</Callout>

Telnyx provides a URL Shortening service with custom links in order to improve brand awareness and bypass spam filters that block most popular URL shortening sites. Any message that contains URLs with the supported domains will be converted into one of Telnyx's custom shortened URLs. Check out the guide below for details, and make sure you [sign up for a free Telnyx account](https://telnyx.com/sign-up?lang=mission%20control%20portal) before you get started!

## How it works

When URL Shortening is turned on, any messages that contains base URLs from the supported URLs will be converted to a URL with a base domain of your choosing.Custom shortened URLs give brand exposure, are more memorable, and boost your audience's trust.

Let's take a look at how custom URL shortening works - if you were to send a message that looked like the following payload object:

```json theme={null}
{
  ...
  "text": "Your shift is starting soon: https://bit.ly/78ejf9n"
  ...
}
```

<Callout type="info">
  After pasting the above content, Kindly check and remove any new line added
</Callout>

URL Shortening will turn the message into:

```json theme={null}
{
    ...
    "text": "Your shift is starting soon: http://scdlchg.cc/b20",
    ...
}
```

<Callout type="info">
  After pasting the above content, Kindly check and remove any new line added
</Callout>

## Supported domains in shortened URLs

By default, if URL Shortening is enabled on the messaging profile, only URLs with the following domains will be converted:

* bit.do
* bit.ly
* carebank.site
* drvline.site
* eatngage.com
* goo.gl
* healthsettle.pw
* ht.ly
* is.gd
* ow\.ly
* rebrand.ly
* t.co
* tiny.cc
* tinyurl.com
* x.co

<Callout type="info">
  You have the option of expanding the URL shortening for all domains. You can disable the <code>Replace Blacklist Only</code> setting in the URL Shortener settings on your messaging profile.
</Callout>

## Message engagement reports

In addition to custom URL shortening, you can also view how often recipients of your messages have opened the link via the [Message Engagement Report](https://portal.telnyx.com/?_gl=1*1iw3cdz*_ga*MTgyNTcxMzMwNy4xNjQ3MjMyNDY4*_ga_ZPM4K1DLND*MTY3NjU0MTg5OC4xNzEuMS4xNjc2NTQyMzM2LjU5LjAuMA..#/login/sign-in).

1. Select a Start Date and End Date for the time range you wish to report on.
2. Select the Messaging Profiles you wish to report on.
3. Click on Generate Messaging Report.
4. (Optionally) You can also download a detailed view of the clicks.

## Receiving link click Webhooks

If you want to track user engagement with your custom shortened URL in real time, you have the option of receiving webhooks when a shortened link is clicked.

You can enable receiving webhooks on a per messaging profile basis. Webhooks will be sent to the webhooks already configured on the messaging profile.

## Mission control portal

### How do I create a custom shortened URL?

Custom URL Shortening is enabled per Messaging Profile. If you send SMS via phone numbers under this profile, and they contain any URLs that are part of the list of supported URLs, then they will be replaced with links that the URL Shortener service generates.

Please reach out to customer support so that they can work internally to create your customer URL shortener. Please provide the following information so customer support can process your request:

1. Your customer ID
2. Your custom domains (or let us know if you need us to provide the domains for you)
3. The profile IDs that you need the link shortner assigned to

Please note that any domains that you provide need to be set up with AAA records

## cURL

### Basic setup

URL Shortening is enabled per Messaging Profile. If you send SMS via phone numbers under this profile, if they contain any URLs that are part of the list of supported URLs, then they will be replaced with links that the URL Shortener service generates.

The code below enables the url shortener service with a specific domain and a custom identifying prefix. It'll also enable the service for all domains, not just the supported domains listed above and enable receiving webhooks for link clicks.

```bash theme={null}
curl -X PATCH \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"url_shortener_settings":
    {"domain": "arv.fyi",
    "prefix":"custom_prefix",
    "replace_blacklist_only": false,
    "send_webhooks": true}}' \
  "https://api.telnyx.com/v2/messaging_profiles/{YOUR_MESSAGING_PROFILE_ID}"
```

<Callout type="info">
  After pasting the above content, Kindly check and remove any new line added
</Callout>

## Python

### Basic setup

URL Shortening is enabled per Messaging Profile. If you send SMS via phone numbers under this profile, if they contain any URLs that are part of the list of supported URLs, then they will be replaced with links that the URL Shortener service generates.

The code below enables the url shortener service with a specific domain and a custom identifying prefix. It'll also enable the service for all domains, not just the supported domains listed above and enable receiving webhooks for link clicks.

```python theme={null}
import telnyx
telnyx.api_key = "YOUR_API_KEY"

mp = telnyx.MessagingProfile.retrieve("YOUR_MESSAGING_PROFILE_ID")

# turn on number pool
mp.url_shortener_settings = {
  "domain": "arv.fyi",
  "prefix":"custom_prefix",
  "replace_blacklist_only": False,
  "send_webhooks": True
}
mp.save()
```

<Callout type="info">
  After pasting the above content, Kindly check and remove any new line added
</Callout>

## Ruby

### Basic setup

URL Shortening is enabled per Messaging Profile. If you send SMS via phone numbers under this profile, if they contain any URLs that are part of the list of supported URLs, then they will be replaced with links that the URL Shortener service generates.

The code below enables the url shortener service with a specific domain and a custom identifying prefix. It'll also enable the service for all domains, not just the supported domains listed above and enable receiving webhooks for link clicks.

```ruby theme={null}
require "telnyx"
Telnyx.api_key = "YOUR_API_KEY"

mp = Telnyx::MessagingProfile.retrieve("YOUR_MESSAGING_PROFILE_ID")

# turn on number pool

mp.number_pool_settings = {
  domain: "arv.fyi",
  prefix: "custom_prefix",
  replace_blacklist_only: false,
  send_webhooks: true
}

mp.save
```

<Callout type="info">
  After pasting the above content, Kindly check and remove any new line added
</Callout>

## Node

### Basic setup

URL Shortening is enabled per Messaging Profile. If you send SMS via phone numbers under this profile, if they contain any URLs that are part of the list of supported URLs, then they will be replaced with links that the URL Shortener service generates.

The code below enables the url shortener service with a specific domain and a custom identifying prefix. It'll also enable the service for all domains, not just the supported domains listed above and enable receiving webhooks for link clicks.

```javascript theme={null}
import Telnyx from 'telnyx';

const telnyx = new Telnyx("YOUR_API_KEY");

const { data : messagingProfile } = await telnyx.messagingProfiles.update(
  'YOUR_MESSAGING_PROFILE_ID',
  {
    "url_shortener_settings": {
      "domain": "arv.fyi",
      "prefix":"custom_prefix",
      "replace_blacklist_only": false,
      "send_webhooks": true
    }
  }
)
```

<Callout type="info">
  After pasting the above content, Kindly check and remove any new line added
</Callout>

## PHP

### Basic setup

URL Shortening is enabled per Messaging Profile. If you send SMS via phone numbers under this profile, if they contain any URLs that are part of the list of supported URLs, then they will be replaced with links that the URL Shortener service generates.

The code below enables the url shortener service with a specific domain and a custom identifying prefix. It'll also enable the service for all domains, not just the supported domains listed above and enable receiving webhooks for link clicks.

```php theme={null}
\Telnyx\Telnyx::setApiKey('YOUR_API_KEY');

\Telnyx\MessagingProfile::Update("YOUR_MESSAGING_PROFILE_ID", ["url_shortener_settings" => {
  "domain": "arv.fyi",
  "prefix":"custom_prefix",
  "replace_blacklist_only": false,
   "send_webhooks": true
}]);
```

<Callout type="info">
  After pasting the above content, Kindly check and remove any new line added
</Callout>

## .NET

### Basic setup

URL Shortening is enabled per Messaging Profile. If you send SMS via phone numbers under this profile, if they contain any URLs that are part of the list of supported URLs, then they will be replaced with links that the URL Shortener service generates.

The code below enables the url shortener service with a specific domain and a custom identifying prefix. It'll also enable the service for all domains, not just the supported domains listed above and enable receiving webhooks for link clicks.

```csharp theme={null}
using System;
using Telnyx.net.Services.VerifyAPI;
private static string TELNYX_API_KEY ="TELNYX_API_KEY";

Telnyx.TelnyxConfiguration.SetApiKey(TELNYX_API_KEY);
VerificationService verifyService = new VerificationService();

string webhookURL = "";
string domain = "";
string prefix = "";

var messagingProfile = new Telnyx.MessagingProfileService()
var stuff = new Telnyx.MessagingProfileUpdate
  {
     UrlShortenerSettings = {
       Domain = doomain,
       Prefix = prefix,
       ReplaceBlackListOnly = true,
       SendWebhooks = false
     }
  };
messagingProfile.Update(webhookURL, stuff);
```

<Callout type="info">
  After pasting the above content, Kindly check and remove any new line added
</Callout>