Ссылки с UTM-метками
Короткие ссылки компании вида `https://api.aisar.app/l/<код>`, которые ведут клиента прямо в мессенджер выбранного канала и несут набор UTM-меток. Когда клиент по такой ссылке пишет, у контакта появляется касание с этими метками. Группа доступна только бизнес-компаниям (с 2026-11-17).
Куда ведёт ссылка
Адрес назначения строит сервер только из данных канала (номер, username или страница), по которому создана ссылка. Ни один параметр запроса к короткой ссылке в него не попадает. Поддерживаемые типы каналов:
| Тип канала | Адрес назначения | Как AISAR узнаёт ссылку |
|---|---|---|
whatsapp, whatsapp_business | https://wa.me/<номер>?text=<текст> | Маркер #<код> в тексте, который клиент отправляет |
telegram, telegram_business | https://t.me/<username>?text=<текст> или https://t.me/+<номер>?text=<текст> | Маркер #<код> в тексте |
telegram_bot | https://t.me/<бот>?start=<код> | Параметр start, который Telegram передаёт боту при нажатии «Start» |
instagram_business | https://ig.me/m/<username>?ref=<код> | Параметр ref, который Meta передаёт с первым сообщением нового диалога |
facebook_messenger | https://m.me/<id страницы>?ref=<код> | Параметр ref, как у Instagram |
Остальные типы каналов (Instagram без Meta, Threads, онлайн-чат, телефония, почта) не поддерживаются. Текст для WhatsApp и Telegram складывается из prefill_text и маркера #<код> в конце, если marker_enabled = true (по умолчанию). Без маркера касание по такой ссылке не записывается: AISAR не по чему её узнать. Готовый адрес и текст отдаются в preview_url и preview_text, собирать их у себя не нужно.
Публичный переход /l/{code}
GETилиHEAD https://api.aisar.app/l/<код>без авторизации отвечает302на адрес мессенджера. Код состоит из 8 символов: строчная латинская буква и ещё 7 строчных букв или цифр. Ответ без cookie, сCache-Control: no-store.- Неизвестный код, архивная ссылка, удалённый, архивный или отключённый канал, а также адрес канала, который не проходит проверку, дают
404. Адрес канала проверяется при каждом переходе. - Каждый переход увеличивает
clicks_countи обновляетlast_clicked_at.HEAD-запросы, которыми мессенджеры строят превью ссылки, тоже считаются, поэтому счётчик ориентировочный. Больше 600 переходов в минуту по одному коду не считаются, но переход всё равно выполняется. - С одного IP-адреса принимается до 300 переходов в минуту, сверх этого
429сRetry-After.
Поля ссылки
name: обязательное при создании, до 120 символов. Это название видно в касаниях контакта и в переменной сценариев{{contact.source_link}}.channel_id: обязательное при создании, канал текущей компании. После создания не меняется.utm_source,utm_medium,utm_campaign,utm_content,utm_term: необязательные строки до 255 символов. Пустая строка сохраняется какnull.prefill_text: необязательный текст сообщения до 300 символов. Используется только у WhatsApp и Telegram (uses_textвchannel-options).marker_enabled: добавлять ли маркер#<код>в текст, по умолчаниюtrue.codeвыдаёт сервер, он уникален и не меняется.codeиchannel_idвPATCHдают422.
В ответе, кроме этих полей: short_url, channel ({id, name, type}), preview_url, preview_text (только у WhatsApp и Telegram, иначе null), address_problem (код причины, по которой ссылка сейчас не ведёт в канал, или null), clicks_count, touches_count (сколько касаний записано по ссылке), last_clicked_at, archived_at, created_at, created_by ({id, name}).
Архив и удаление
Архивная ссылка перестаёт открываться (404), и её маркер в тексте больше не даёт касаний. restore возвращает её. Удалить насовсем можно только архивную ссылку, по которой не записано ни одного касания: так история контактов не теряет название ссылки. Иначе 409 с кодом not_archived или has_touches.
Права и ограничения
- Права:
tracking_link.view(список иchannel-options),tracking_link.create,tracking_link.update(правка, архив, восстановление),tracking_link.delete. Стандартные роли: администратор получает все четыре, менеджерview,create,update, оператор толькоview. - Запись требует полного API-токена; встроенные (embed) токены и токены сессии подключения получают
403и на чтение. - Семейные (kids) компании получают
403. - Не больше 60 запросов в минуту на пользователя ко всей группе.
Коды ошибок
| Ответ и код | Когда |
|---|---|
422 channel_not_found | channel_id не найден среди каналов текущей компании. |
422 channel_type_unsupported | Тип канала не поддерживается (см. таблицу выше). |
422 channel_not_connected | Канал удалён, в архиве или не подключён. |
422 channel_address_missing | У канала нет адреса, по которому можно открыть чат: номера, username или id страницы. |
409 not_archived | DELETE ссылки, которая не в архиве. Сначала archive. |
409 has_touches | DELETE архивной ссылки, по которой уже есть касания. Такую ссылку можно только держать в архиве. |
404 | Ссылка не найдена в текущей компании. |
403 | Нет нужного права, токен не полный (для записи), встроенный токен или семейная компания. |
Ошибки 422 и 409 с кодом приходят в виде {"data": {"message": "<код>", "error_code": "<код>"}}, у 422 ещё errors.channel_id. Ошибки проверки полей (name пустое, слишком длинная строка) приходят в обычном формате 422 с errors по полям.
Эндпоинты
| Метод | Путь | Описание |
|---|---|---|
| GET | /v1/tracking-linksСписок ссылок компании, новые сверху (query: archived=1 — только архивные, иначе только активные; channel_id; page; per_page до 100, по умолчанию 50). | Список ссылок компании, новые сверху (query: archived=1 — только архивные, иначе только активные; channel_id; page; per_page до 100, по умолчанию 50). |
| GET | /v1/tracking-links/channel-optionsНеархивные каналы поддерживаемых типов: id, name, type, account_name, uses_text, address_ok, address_problem. | Неархивные каналы поддерживаемых типов: id, name, type, account_name, uses_text, address_ok, address_problem. |
| POST | /v1/tracking-linksСоздать ссылку (body: channel_id, name, utm_*, prefill_text, marker_enabled) — 201 с объектом ссылки. | Создать ссылку (body: channel_id, name, utm_*, prefill_text, marker_enabled) — 201 с объектом ссылки. |
| PATCH | /v1/tracking-links/{trackingLink}Изменить название, UTM-метки, текст или маркер. code и channel_id не меняются (422). | Изменить название, UTM-метки, текст или маркер. code и channel_id не меняются (422). |
| POST | /v1/tracking-links/{trackingLink}/archiveОтправить ссылку в архив: она перестаёт открываться и давать касания. | Отправить ссылку в архив: она перестаёт открываться и давать касания. |
| POST | /v1/tracking-links/{trackingLink}/restoreВернуть ссылку из архива. | Вернуть ссылку из архива. |
| DELETE | /v1/tracking-links/{trackingLink}Удалить архивную ссылку без касаний — 204; иначе 409 not_archived или has_touches. | Удалить архивную ссылку без касаний — 204; иначе 409 not_archived или has_touches. |
Примеры
Создание ссылки на WhatsApp
Запрос
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"
}'Ответ
{
"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" }
}
}Список активных ссылок
Запрос
curl -X GET "https://api.aisar.app/v1/tracking-links?per_page=20" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/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 }
}
}Каналы, на которые можно сделать ссылку
Запрос
curl -X GET "https://api.aisar.app/v1/tracking-links/channel-options" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/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" }
]
}
}Удаление ссылки с касаниями
Запрос
curl -X DELETE "https://api.aisar.app/v1/tracking-links/31" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"Ответ
{
"data": {
"message": "has_touches",
"error_code": "has_touches"
}
}