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

Сегменты

Сегменты контактов — переиспользуемые определения аудитории на основе условий (теги, канал, статус, поля, активность) или статичного списка участников. Используются при создании рассылок и как триггер в автоматизациях. Размер аудитории можно оценить без сохранения сегмента через /segments/estimate.

Типы условий

Поддерживаемые типы условий: tag, channel, status, date, field, activity, custom; условия объединяются логикой group_logic (and или or).

Пагинация и поиск

Список (GET /segments) поддерживает пагинацию (page, perPage — по умолчанию 50) и поиск (search).

Статические сегменты: идентификатор участника

В статическом сегменте (type: "static") каждый участник (members[]) задаётся полем identifier — номером телефона. Поскольку номера обычно вставляются из таблиц и CRM-выгрузок, сервер (с 2026-09-09, в POST /segments, POST|PATCH /segments/{segment} и POST /segments/estimate) нормализует значение до отправки на валидацию: убирает пробелы, скобки, дефисы и обрамляющие кавычки, отбрасывает международный префикс 00, а казахстанско-российскую форму из 11 цифр с ведущей 8 (8XXXXXXXXXX) превращает в +7XXXXXXXXXX. После нормализации значение должно быть телефоном в формате +<цифры> (7–15 цифр, без ведущего нуля) — иначе запрос отклоняется с 422 и ошибкой на members.N.identifier: Each member identifier must be a phone number in international format (7–15 digits). Дубликаты, совпавшие после нормализации, схлопываются в одного участника. В ответе members[].identifier возвращается уже в нормализованном виде.

Эндпоинты

МетодПуть
GET/v1/segments

Список сегментов (пагинация, поиск)

POST/v1/segments

Создание сегмента

PATCH/v1/segments/{segment}

Обновление сегмента

POST/v1/segments/{segment}

Обновление сегмента (алиас PATCH для клиентов без PATCH)

DELETE/v1/segments/{segment}

Удаление сегмента

POST/v1/segments/estimate

Оценка размера аудитории по условиям (без сохранения)

Примеры

Создание динамического сегмента

Запрос

bash
curl -X POST https://api.aisar.app/v1/segments \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New leads",
    "description": "Contacts with recent inbound activity",
    "conditions": [
      { "type": "tag", "operator": "has_any", "value": [1, 2], "group": 0 },
      { "type": "channel", "operator": "in", "value": [7], "group": 0 }
    ],
    "group_logic": "and"
  }'

Ответ

json
{
  "data": {
    "id": "45",
    "name": "New leads",
    "slug": "new-leads",
    "type": "dynamic",
    "description": "Contacts with recent inbound activity",
    "conditions": [
      { "group": 0, "type": "tag", "operator": "has_any", "value": [1, 2], "field_name": null },
      { "group": 0, "type": "channel", "operator": "in", "value": [7], "field_name": null }
    ],
    "conditions_summary": "Tag in (Lead, Hot) AND channel is WhatsApp",
    "estimated_count": 120,
    "contacts_count": null,
    "members": null,
    "created_at": "2026-03-15T10:00:00.000000Z",
    "updated_at": "2026-03-15T10:00:00.000000Z"
  }
}

Оценка аудитории без сохранения

Запрос

bash
curl -X POST https://api.aisar.app/v1/segments/estimate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "type": "tag", "operator": "has_any", "value": [1, 2], "group": 0 }
    ]
  }'

Ответ

json
{
  "data": {
    "estimated_count": 120
  }
}

Обновление сегмента

Запрос

bash
curl -X PATCH https://api.aisar.app/v1/segments/46 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hot leads",
    "description": "High-intent contacts from priority channels",
    "conditions": [
      { "type": "tag", "operator": "has_any", "value": [2], "group": 0 },
      { "type": "status", "operator": "is", "value": "open", "group": 0 }
    ],
    "group_logic": "and"
  }'

Ответ

json
{
  "data": {
    "id": "46",
    "name": "Hot leads",
    "slug": "hot-leads",
    "type": "dynamic",
    "description": "High-intent contacts from priority channels",
    "conditions": [
      { "group": 0, "type": "tag", "operator": "has_any", "value": [2], "field_name": null },
      { "group": 0, "type": "status", "operator": "is", "value": "open", "field_name": null }
    ],
    "conditions_summary": "Tag in (Hot) AND status is open",
    "estimated_count": 64,
    "contacts_count": null,
    "members": null,
    "created_at": "2026-03-15T10:00:00.000000Z",
    "updated_at": "2026-03-16T09:30:00.000000Z"
  }
}

Статический сегмент со списком номеров (нормализация и дедупликация)

Запрос

bash
curl -X POST https://api.aisar.app/v1/segments \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Conference attendees",
    "type": "static",
    "members": [
      { "identifier": "1 (202) 555-01-87", "display_name": "Aigerim" },
      { "identifier": "\"905336607106\"" },
      { "identifier": "0012025550187" }
    ]
  }'

Ответ

json
{
  "data": {
    "id": "52",
    "name": "Conference attendees",
    "slug": "conference-attendees",
    "type": "static",
    "description": null,
    "conditions": [],
    "conditions_summary": null,
    "estimated_count": null,
    "contacts_count": 2,
    "members": [
      { "identifier": "+12025550187", "display_name": "Aigerim" },
      { "identifier": "+905336607106", "display_name": null }
    ],
    "created_at": "2026-09-09T10:00:00.000000Z",
    "updated_at": "2026-09-09T10:00:00.000000Z"
  }
}

Ошибка: идентификатор не является телефоном

Запрос

bash
curl -X POST https://api.aisar.app/v1/segments \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Broken import",
    "type": "static",
    "members": [
      { "identifier": "email:client@example.com" }
    ]
  }'

Ответ

json
{
  "message": "The members.0.identifier field format is invalid.",
  "errors": {
    "members.0.identifier": [
      "Each member identifier must be a phone number in international format (7\u201315 digits)."
    ]
  }
}