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 type | Destination | How AISAR recognises the link |
|---|---|---|
whatsapp, whatsapp_business | https://wa.me/<number>?text=<text> | The #<code> marker in the text the client sends |
telegram, telegram_business | https://t.me/<username>?text=<text> or https://t.me/+<number>?text=<text> | The #<code> marker in the text |
telegram_bot | https://t.me/<bot>?start=<code> | The start parameter Telegram passes to the bot when the client taps "Start" |
instagram_business | https://ig.me/m/<username>?ref=<code> | The ref parameter Meta passes with the first message of a new conversation |
facebook_messenger | https://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}
GETorHEAD https://api.aisar.app/l/<code>without authentication answers302to 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 carriesCache-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_countand updateslast_clicked_at.HEADrequests 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
429withRetry-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 asnull.prefill_text: an optional message text up to 300 characters. Used only by WhatsApp and Telegram (uses_textinchannel-options).marker_enabled: whether to add the#<code>marker to the text,trueby default.codeis issued by the server, it is unique and never changes.codeandchannel_idinPATCHgive422.
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 andchannel-options),tracking_link.create,tracking_link.update(edit, archive, restore),tracking_link.delete. Standard roles: the administrator gets all four, the managerview,create,update, the agentviewonly. - Writes need a full API token; embedded tokens and connect-session tokens get
403even on reads. - Family (kids) companies get
403. - At most 60 requests a minute per user across the whole group.
Error codes
| Status and code | When |
|---|---|
422 channel_not_found | channel_id is not among the current company's channels. |
422 channel_type_unsupported | The channel type is not supported (see the table above). |
422 channel_not_connected | The channel is deleted, archived or not connected. |
422 channel_address_missing | The channel has no address a chat can be opened with: a number, a username or a page id. |
409 not_archived | DELETE of a link that is not archived. Call archive first. |
409 has_touches | DELETE of an archived link that already has touches. Such a link can only stay archived. |
404 | The link is not found in the current company. |
403 | The 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
| Method | Path | Summary |
|---|---|---|
| GET | /v1/tracking-linksList 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). | 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-optionsNon-archived channels of supported types: id, name, type, account_name, uses_text, address_ok, address_problem. | Non-archived channels of supported types: id, name, type, account_name, uses_text, address_ok, address_problem. |
| POST | /v1/tracking-linksCreate a link (body: channel_id, name, utm_*, prefill_text, marker_enabled) — 201 with the link object. | 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). | Change the name, UTM tags, text or marker. code and channel_id cannot be changed (422). |
| POST | /v1/tracking-links/{trackingLink}/archiveArchive a link: it stops opening and producing touches. | Archive a link: it stops opening and producing touches. |
| POST | /v1/tracking-links/{trackingLink}/restoreRestore a link from the archive. | 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. | Delete an archived link with no touches — 204; otherwise 409 not_archived or has_touches. |
Examples
Create a WhatsApp link
Request
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
{
"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
curl -X GET "https://api.aisar.app/v1/tracking-links?per_page=20" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Response
{
"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
curl -X GET "https://api.aisar.app/v1/tracking-links/channel-options" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Response
{
"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
curl -X DELETE "https://api.aisar.app/v1/tracking-links/31" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Response
{
"data": {
"message": "has_touches",
"error_code": "has_touches"
}
}