DocumentationEngagement Platform API
Sign inGet started
Guides
API

Short Links in Message Templates

Short links replace the URLs in a template with shortened, trackable links on a Bird or custom domain. Enabling them gives you click tracking on template links and keeps long URLs out of the rendered message.
Short links are supported for whatsapp, sms-messagebird, and rcs-google platform content. Enabling them on a template for any other platform is rejected.

Enabling short links on a template

Short links are configured with the top-level shortLinks object on the channel template create request (and on the PATCH request when updating a draft). See Creating WhatsApp Message Templates for the full create request:
Exemple de code
{
  "defaultLocale": "en",
  "supportedPlatforms": ["whatsapp"],
  "deployments": ["..."],
  "platformContent": ["..."],
  "shortLinks": {
    "enabled": true,
    "domain": "default"
  }
}
FieldTypeDescription
enabledbooleanWhether URLs in this template are shortened
domainstringThe domain the short links are created on. Use "default" for the Bird default domain, or the name of a domain registered in your workspace (see below).
The domain is a plain domain name, not an ID. It must be "default" or a domain registered in your workspace, otherwise the create/update request fails validation with a "short link domain is not allowed" error.

What gets shortened

When short links are enabled, URLs in the template content are replaced at send time. Media URLs are never shortened -- image, file, video, and thumbnail URLs are left untouched. Beyond that, each platform behaves slightly differently:
WhatsApp
  • Only text with a URL scheme (https://...) is treated as a link. A bare domain in the body -- for example Welcome to example.com -- is sent as-is and never shortened.
  • Body text URLs are fully replaced with a short link (e.g. https://example.com/spring-sale becomes https://brd1.eu/hufR276).
  • URL button (link-action) URLs keep the short domain visible in the button target: the button URL becomes https://<domain>/<link-id>.
The WhatsApp app itself renders any domain-like text (such as example.com) as a tappable link on the recipient's device. This client-side behavior is not controlled by Bird or by Meta's template options. To keep such text plain, add a zero-width space (U+200B) on both sides of the dot; the invisible characters become part of the template body that Meta reviews.
SMS
  • Both schemed URLs and bare domains (example.com) are shortened.
  • Short links are sent without the https:// scheme (brd1.eu/hufR276) to save message length.
RCS
  • Both schemed URLs and bare domains are shortened; short links keep the https:// scheme.

Finding the domain your workspace uses

A workspace can have up to three kinds of short link domain, and the active one is chosen by priority:
  1. Custom domain (e.g. links.example.com) -- used if one is registered and verified
  2. Branded subdomain (e.g. bertsbooks.brd3.eu) -- used if registered and no custom domain exists
  3. Bird default domain (e.g. brd1.eu) -- the fallback when nothing is registered
To see which domain is currently active:
Exemple de code
GET https://api.bird.com/workspaces/{workspaceId}/domains/active
To list every short link domain registered in the workspace:
Exemple de code
GET https://api.bird.com/workspaces/{workspaceId}/domains?domainUsedBy=shorturl
Example response:
Exemple de code
{
  "results": [
    {
      "name": "links.example.com",
      "verified": true,
      "active": true,
      "usedBy": "shorturl",
      "verificationToken": {
        "token": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
      },
      "createdAt": "2025-09-19T15:00:15.849Z",
      "updatedAt": "2025-09-19T15:04:31.112Z"
    }
  ]
}
FieldDescription
nameThe domain name -- this is the value to use in the template's shortLinks.domain field
verifiedWhether domain ownership has been verified. Custom domains cannot serve links until verified.
activeWhether this is the domain the workspace currently uses when creating short links

Adding a custom domain

A workspace can register at most one custom domain (and one branded subdomain). You can also manage domains in the dashboard under Settings > Marketing > Custom Domains > Short links -- see Short links in the platform documentation.

1 -- Register the domain

Exemple de code
POST https://api.bird.com/workspaces/{workspaceId}/domains
Exemple de code
{
  "name": "links.example.com",
  "usedBy": "shorturl"
}
The response is the domain object shown above, with verified: false and a verificationToken. Save the token for the next step.
A branded subdomain -- your brand as a subdomain of a Bird domain, such as bertsbooks.brd3.eu -- is registered with this same endpoint and is verified automatically, so steps 2--4 don't apply. List the available base domains with GET /workspaces/{workspaceId}/domains/defaults.

2 -- Get the DNS target

Exemple de code
GET https://api.bird.com/workspaces/{workspaceId}/domains/configurations?domainUsedBy=shorturl
Example response:
Exemple de code
{
  "cname": "<CNAME target returned for your region>",
  "ips": ["<IP address>", "<IP address>"]
}

3 -- Configure DNS at your provider

Add two records for the domain you registered:
Record typeName (host)Value
TXTlinks.example.combird-verification=<verificationToken from step 1>
CNAMElinks.example.comThe cname value from step 2
If your DNS provider does not allow a CNAME on the record you need (for example on an apex domain), create A records pointing to the ips values instead.

4 -- Verify the domain

Exemple de code
POST https://api.bird.com/workspaces/{workspaceId}/domains/{domainName}/verify
Verification checks the TXT record and that the domain resolves to Bird, then provisions a TLS certificate for it. On success the response returns the domain with verified: true, and it becomes the workspace's active short link domain.
DNS changes can take time to propagate. Bird also retries verification automatically for a period after the domain is created, so a domain may flip to verified on its own once the records are visible.

Related