Перейти к содержимому
AISARAISAR
REST API

Ссылки с UTM-метками

Короткие ссылки компании вида `https://api.aisar.app/l/<код>`, которые ведут клиента прямо в мессенджер выбранного канала и несут набор UTM-меток. Когда клиент по такой ссылке пишет, у контакта появляется касание с этими метками. Группа доступна только бизнес-компаниям (с 2026-11-17).

Куда ведёт ссылка

Адрес назначения строит сервер только из данных канала (номер, username или страница), по которому создана ссылка. Ни один параметр запроса к короткой ссылке в него не попадает. Поддерживаемые типы каналов:

Тип каналаАдрес назначенияКак AISAR узнаёт ссылку
whatsapp, whatsapp_businesshttps://wa.me/<номер>?text=<текст>Маркер #<код> в тексте, который клиент отправляет
telegram, telegram_businesshttps://t.me/<username>?text=<текст> или https://t.me/+<номер>?text=<текст>Маркер #<код> в тексте
telegram_bothttps://t.me/<бот>?start=<код>Параметр start, который Telegram передаёт боту при нажатии «Start»
instagram_businesshttps://ig.me/m/<username>?ref=<код>Параметр ref, который Meta передаёт с первым сообщением нового диалога
facebook_messengerhttps://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_foundchannel_id не найден среди каналов текущей компании.
422 channel_type_unsupportedТип канала не поддерживается (см. таблицу выше).
422 channel_not_connectedКанал удалён, в архиве или не подключён.
422 channel_address_missingУ канала нет адреса, по которому можно открыть чат: номера, username или id страницы.
409 not_archivedDELETE ссылки, которая не в архиве. Сначала archive.
409 has_touchesDELETE архивной ссылки, по которой уже есть касания. Такую ссылку можно только держать в архиве.
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).

GET/v1/tracking-links/channel-options

Неархивные каналы поддерживаемых типов: 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 с объектом ссылки.

PATCH/v1/tracking-links/{trackingLink}

Изменить название, 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.

Примеры

Создание ссылки на WhatsApp

Запрос

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"
  }'

Ответ

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" }
  }
}

Список активных ссылок

Запрос

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

Ответ

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 }
  }
}

Каналы, на которые можно сделать ссылку

Запрос

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

Ответ

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" }
    ]
  }
}

Удаление ссылки с касаниями

Запрос

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

Ответ

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