Skip to content
AISARAISAR
REST API

UTM tracking links

Short company links like `https://api.aisar.app/l/<code>` that take the client straight into the messenger of a chosen channel and carry a set of UTM tags. When the client writes through such a link, the contact gets a touch with these tags. The group is available to business companies only (since 2026-11-17).

Where a link leads

The server builds the destination only from the data of the channel the link was created for (its number, username or page). No parameter of the request to the short link gets into it. Supported channel types:

Channel typeDestinationHow AISAR recognises the link
whatsapp, whatsapp_businesshttps://wa.me/<number>?text=<text>The #<code> marker in the text the client sends
telegram, telegram_businesshttps://t.me/<username>?text=<text> or https://t.me/+<number>?text=<text>The #<code> marker in the text
telegram_bothttps://t.me/<bot>?start=<code>The start parameter Telegram passes to the bot when the client taps "Start"
instagram_businesshttps://ig.me/m/<username>?ref=<code>The ref parameter Meta passes with the first message of a new conversation
facebook_messengerhttps://m.me/<page id>?ref=<code>The ref parameter, as for Instagram

Other channel types (Instagram without Meta, Threads, live chat, telephony, email) are not supported. The text for WhatsApp and Telegram is prefill_text followed by the #<code> marker when marker_enabled = true (the default). Without the marker a touch through such a link is not recorded: AISAR has nothing to recognise it by. The ready address and text come in preview_url and preview_text, there is no need to build them yourself.

The public redirect /l/{code}

  • GET or HEAD https://api.aisar.app/l/<code> without authentication answers 302 to the messenger address. The code is 8 characters: a lowercase Latin letter followed by 7 lowercase letters or digits. The response sets no cookie and carries Cache-Control: no-store.
  • An unknown code, an archived link, a deleted, archived or disconnected channel, and a channel address that fails validation give 404. The channel address is checked on every redirect.
  • Every redirect increments clicks_count and updates last_clicked_at. HEAD requests that messengers use to build link previews are counted too, so the counter is approximate. Beyond 600 redirects a minute per code the clicks are not counted, but the redirect still happens.
  • One IP address gets up to 300 redirects a minute, beyond that 429 with Retry-After.

Link fields

  • name: required on create, up to 120 characters. The name shows in the contact's touches and in the scenario variable {{contact.source_link}}.
  • channel_id: required on create, a channel of the current company. It cannot be changed after creation.
  • utm_source, utm_medium, utm_campaign, utm_content, utm_term: optional strings up to 255 characters. An empty string is stored as null.
  • prefill_text: an optional message text up to 300 characters. Used only by WhatsApp and Telegram (uses_text in channel-options).
  • marker_enabled: whether to add the #<code> marker to the text, true by default.
  • code is issued by the server, it is unique and never changes. code and channel_id in PATCH give 422.

Besides these fields the response has: short_url, channel ({id, name, type}), preview_url, preview_text (WhatsApp and Telegram only, otherwise null), address_problem (the reason code why the link does not lead into the channel right now, or null), clicks_count, touches_count (how many touches were recorded through the link), last_clicked_at, archived_at, created_at, created_by ({id, name}).

Archive and deletion

An archived link stops opening (404), and its marker in a text no longer produces touches. restore brings it back. Only an archived link with no recorded touches can be deleted for good: this way the contacts' history never loses the link name. Otherwise 409 with the code not_archived or has_touches.

Permissions and limits

  • Permissions: tracking_link.view (the list and channel-options), tracking_link.create, tracking_link.update (edit, archive, restore), tracking_link.delete. Standard roles: the administrator gets all four, the manager view, create, update, the agent view only.
  • Writes need a full API token; embedded tokens and connect-session tokens get 403 even on reads.
  • Family (kids) companies get 403.
  • At most 60 requests a minute per user across the whole group.

Error codes

Status and codeWhen
422 channel_not_foundchannel_id is not among the current company's channels.
422 channel_type_unsupportedThe channel type is not supported (see the table above).
422 channel_not_connectedThe channel is deleted, archived or not connected.
422 channel_address_missingThe channel has no address a chat can be opened with: a number, a username or a page id.
409 not_archivedDELETE of a link that is not archived. Call archive first.
409 has_touchesDELETE of an archived link that already has touches. Such a link can only stay archived.
404The link is not found in the current company.
403The permission is missing, the token is not full (for writes), an embedded token, or a family company.

The 422 and 409 errors with a code come as {"data": {"message": "<code>", "error_code": "<code>"}}, the 422 also has errors.channel_id. Field validation errors (an empty name, a too long string) come in the usual 422 format with per-field errors.

Endpoints

MethodPath
GET/v1/tracking-links

List the company's links, newest first (query: archived=1 for archived only, otherwise active only; channel_id; page; per_page up to 100, default 50).

GET/v1/tracking-links/channel-options

Non-archived channels of supported types: id, name, type, account_name, uses_text, address_ok, address_problem.

POST/v1/tracking-links

Create a link (body: channel_id, name, utm_*, prefill_text, marker_enabled) — 201 with the link object.

PATCH/v1/tracking-links/{trackingLink}

Change the name, UTM tags, text or marker. code and channel_id cannot be changed (422).

POST/v1/tracking-links/{trackingLink}/archive

Archive a link: it stops opening and producing touches.

POST/v1/tracking-links/{trackingLink}/restore

Restore a link from the archive.

DELETE/v1/tracking-links/{trackingLink}

Delete an archived link with no touches — 204; otherwise 409 not_archived or has_touches.

Examples

Create a WhatsApp link

Request

bash
curl -X POST "https://api.aisar.app/v1/tracking-links" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": 12,
    "name": "Autumn flyer",
    "utm_source": "flyer",
    "utm_medium": "offline",
    "utm_campaign": "autumn_sale",
    "prefill_text": "Hello! I would like to know more"
  }'

Response

json
{
  "data": {
    "id": 31,
    "name": "Autumn flyer",
    "code": "k7m2x9q1",
    "short_url": "https://api.aisar.app/l/k7m2x9q1",
    "channel": { "id": 12, "name": "Sales WhatsApp", "type": "whatsapp" },
    "utm_source": "flyer",
    "utm_medium": "offline",
    "utm_campaign": "autumn_sale",
    "utm_content": null,
    "utm_term": null,
    "prefill_text": "Hello! I would like to know more",
    "marker_enabled": true,
    "preview_url": "https://wa.me/1XXX55501XX?text=Hello%21%20I%20would%20like%20to%20know%20more%20%23k7m2x9q1",
    "preview_text": "Hello! I would like to know more #k7m2x9q1",
    "address_problem": null,
    "clicks_count": 0,
    "touches_count": 0,
    "last_clicked_at": null,
    "archived_at": null,
    "created_at": "2026-11-17T10:00:00.000000Z",
    "created_by": { "id": 5, "name": "Jane Smith" }
  }
}

List active links

Request

bash
curl -X GET "https://api.aisar.app/v1/tracking-links?per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

json
{
  "data": {
    "items": [
      {
        "id": 31,
        "name": "Autumn flyer",
        "code": "k7m2x9q1",
        "short_url": "https://api.aisar.app/l/k7m2x9q1",
        "channel": { "id": 12, "name": "Sales WhatsApp", "type": "whatsapp" },
        "utm_source": "flyer",
        "utm_medium": "offline",
        "utm_campaign": "autumn_sale",
        "utm_content": null,
        "utm_term": null,
        "prefill_text": "Hello! I would like to know more",
        "marker_enabled": true,
        "preview_url": "https://wa.me/1XXX55501XX?text=Hello%21%20I%20would%20like%20to%20know%20more%20%23k7m2x9q1",
        "preview_text": "Hello! I would like to know more #k7m2x9q1",
        "address_problem": null,
        "clicks_count": 48,
        "touches_count": 17,
        "last_clicked_at": "2026-11-17T15:42:10.000000Z",
        "archived_at": null,
        "created_at": "2026-11-17T10:00:00.000000Z",
        "created_by": { "id": 5, "name": "Jane Smith" }
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "total": 1, "lastPage": 1 }
  }
}

Channels a link can lead to

Request

bash
curl -X GET "https://api.aisar.app/v1/tracking-links/channel-options" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

json
{
  "data": {
    "items": [
      { "id": 12, "name": "Sales WhatsApp", "type": "whatsapp", "account_name": "+1 XXX 555 01XX", "uses_text": true, "address_ok": true, "address_problem": null },
      { "id": 14, "name": "Shop bot", "type": "telegram_bot", "account_name": "@example_shop_bot", "uses_text": false, "address_ok": true, "address_problem": null },
      { "id": 15, "name": "Support WhatsApp", "type": "whatsapp_business", "account_name": "+1 XXX 555 01XX", "uses_text": true, "address_ok": false, "address_problem": "channel_not_connected" }
    ]
  }
}

Deleting a link that has touches

Request

bash
curl -X DELETE "https://api.aisar.app/v1/tracking-links/31" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

json
{
  "data": {
    "message": "has_touches",
    "error_code": "has_touches"
  }
}