Фильтры чатов в API

Фильтр чатов — это условия, по которым API отбирает чаты: например, «непрочитанные», «с тегом Оплатил» или «пришли из Google». Один и тот же фильтр работает в поиске, подсчёте, выгрузке и подписке на

Обновлено 2 ноября 2026 г.5 мин

В статье — как устроен фильтр, все поля и операторы и готовые примеры, которые можно скопировать.

Где работает фильтр чатов

Запрос	Что делает
`POST /chats/v1/search`	Список чатов
`POST /chats/v1/stats`	Сколько чатов в каждом статусе
`POST /chats/v1/export`	Выгрузка всех чатов — Как выгрузить все чаты через API
`POST /chats/v1/realtime`	События по чатам в реальном времени — Новые сообщения в реальном времени через API

Фильтр передаётся в поле filter тела запроса, рядом с bot_id.

Фильтр из одного условия

Условие фильтра состоит из трёх частей: поле field, оператор operator и значение value. Например, условие ниже отбирает чаты в статусе manual:

{
  "bot_id": "ID_БОТА",
  "filter": { "field": "status", "operator": "is", "value": "manual" }
}

Читается так: «статус — равен — manual».

Несколько условий: группы and и or

Чтобы объединить условия фильтра, положите их в группу с полями logic и filters. "logic": "and" — должны выполняться все условия, "or" — хотя бы одно.

{
  "bot_id": "ID_БОТА",
  "filter": {
    "logic": "and",
    "filters": [
      { "field": "status", "operator": "is", "value": "manual" },
      { "field": "incoming_unread_count", "operator": "more_number", "value": 0 }
    ]
  }
}

Группы можно вкладывать друг в друга. Здесь — чаты с тегом, которые ведёт оператор или AI:

{
  "logic": "and",
  "filters": [
    { "field": "tags", "operator": "has_any", "value": ["ID_ТЕГА"] },
    {
      "logic": "or",
      "filters": [
        { "field": "status", "operator": "is", "value": "manual" },
        { "field": "status", "operator": "is", "value": "ai" }
      ]
    }
  ]
}

Ограничения одного фильтра:

до 64 условий и групп;

до 5 уровней вложенности;

до 100 значений в одном списке.

Поля фильтра: поиск, статус, ответственный

Поле field в условии фильтра — то, что проверяется. Поиск по клиенту, статус чата, кто писал последним, непрочитанные и ответственный:

Поле	Что проверяет	Операторы	Значение
`query`	Имя, username или Telegram id клиента	Без оператора	Текст до 128 символов
`status`	Статус чата	`is`, `is_any`, `is_not`	`manual`, `ai`, `waiting`, `ignore`, `blocked`, `error`, `stopped`, `finished`, `start`, `lead`
`last_message_sender_type`	Кто написал последним	`is`, `is_any`, `is_not`	`incoming` — клиент, `outcoming` — ваша сторона
`incoming_unread_count`	Непрочитанные сообщения клиента	Числовые	Число
`assign_id`	Ответственный	`is`, `is_any`, `is_not`, `is_empty`, `is_not_empty`	id участника Space

Что такое ignore

ignore — не отдельный статус, а вопрос: чат в статусе manual, и последнее сообщение пришло от клиента. Значит, клиенту должны ответить.

Поля фильтра: теги, кастомные поля, Tracker

Теги и кастомные поля фильтруются только по id, а не по названию. Для custom_fields и tracker_fields в условии нужен ещё key:

Поле	Что проверяет	Операторы	Значение
`tags`	Теги чата	`has_any`, `has_all`, `has_only`, `has_none`, `is_not_empty`	Список id тегов
`custom_fields`	Значение поля	`is`, `is_not`, `is_any`	Плюс `key` — id поля
`tracker_fields`	Метка Tracker, например `utm_source`	`is`, `is_not`, `is_any`	Плюс `key` — название метки
`tracker_events`	События Tracker, например покупка	`has_any`, `has_all`, `has_none`, `is_not_empty`	Например, `["purchase"]`

Поля фильтра: даты, сумма, сценарий, id

Даты в фильтре — created_at и updated_at, сумма лида — cost, положение в сценарии — шаг и этап продажи:

Поле	Что проверяет	Операторы	Значение
`created_at`	Когда появился чат	`before`, `after`, `between`	Дата
`updated_at`	Время последнего сообщения	`before`, `after`, `between`	Дата
`cost`	Сумма, привязанная к лиду	Числовые	Число
`current_flow_id`, `current_step_id`	Текущий сценарий и шаг	`is`, `is_any`, `is_not`, `is_empty`, `is_not_empty`	id
`current_sale_stage_id`	Этап продажи	`is`, `is_any`, `is_not`, `is_not_empty`	id
`id`, `external_id`	id чата или Telegram id клиента	`is`, `is_any`, `is_not`	id

Операторы фильтра

Оператор	Значение	Что значит
`is` / `is_not`	Одно значение	Равно / не равно
`is_any`	Список	Равно любому из списка
`is_empty` / `is_not_empty`	Без значения	Поле пустое / заполнено
`has_any`	Список	Есть хотя бы одно из значений
`has_all`	Список	Есть все значения, и, возможно, другие
`has_only`	Список	Есть ровно эти значения и никаких других
`has_none`	Список	Нет ни одного из значений
`before` / `after`	Дата	Строго раньше / строго позже
`between`	Две даты	В промежутке, включая границы
`more_number`, `less_number`, `more_equal_number`, `less_equal_number`, `equal_number`, `not_equal_number`	Число	Больше, меньше, больше или равно, меньше или равно, равно, не равно

Даты в фильтре и часовой пояс

Дату можно записать полностью — 2026-10-01T00:00:00Z — или просто днём: 2026-10-01. Чтобы день считался по вашему времени, а не по UTC, добавьте timezone:

{ "field": "created_at", "operator": "between", "value": ["2026-10-01", "2026-10-31"], "timezone": "Europe/Moscow" }

Примеры фильтров: кому не ответили

Клиенту не ответили

Статус ignore: чат в ручном режиме, и последним написал клиент.

{ "field": "status", "operator": "is", "value": "ignore" }

Не ответили, и чат ни на кого не назначен

Статус ignore и пустой ответственный: assign_id с оператором is_empty.

{
  "logic": "and",
  "filters": [
    { "field": "status", "operator": "is", "value": "ignore" },
    { "field": "assign_id", "operator": "is_empty" }
  ]
}

Примеры фильтров: покупки, поля, даты

Купили, пришли из Google

Метка Tracker utm_source равна google, и у лида есть событие purchase в tracker_events.

{
  "logic": "and",
  "filters": [
    { "field": "tracker_fields", "key": "utm_source", "operator": "is", "value": "google" },
    { "field": "tracker_events", "operator": "has_any", "value": ["purchase"] }
  ]
}

Город из поля — Москва

Кастомное поле «Город» равно «Москва». В key — id поля из GET /bots/v1/{bot_id}/custom-fields.

{ "field": "custom_fields", "key": "ID_ПОЛЯ_ГОРОД", "operator": "is", "value": "Москва" }

Переписка за последние сутки

Последнее сообщение позже указанного времени: updated_at с оператором after.

{ "field": "updated_at", "operator": "after", "value": "2026-10-29T12:00:00Z" }

Сколько чатов в каждом статусе

Число чатов по статусам отдаёт POST /chats/v1/stats. Передайте тот же фильтр, что в поиске, или запрос без фильтра — придут общее число total и счётчики statuses:

curl -X POST 'https://api.chatterfy.ai/public-api/chats/v1/stats' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"bot_id": "ID_БОТА"}'

{
  "total": 3634,
  "statuses": [
    { "status": "waiting", "count": 2980 },
    { "status": "manual", "count": 605 },
    { "status": "ai", "count": 33 },
    { "status": "blocked", "count": 16 },
    { "status": "ignore", "count": 421 }
  ]
}

Чаты ignore — часть чатов manual, поэтому в total они второй раз не считаются.