Сегменты пользователей

Сегмент — готовая аудитория для рассылок и акций: «активные за неделю», «покупатели», «с балансом от 100» и т.п.

Через API можно:

Адрес API: https://api.bot-t.com
Все запросы — POST, тело в JSON.

Как подключиться

В каждом запросе укажите:

Параметр	Обязательно	Что это
`bot_id`	да	ID вашего бота
токен бота или секретный ключ	да	`token` / `botToken` или `secretKey`

Успешный ответ: "result": true и данные в "data".
Ошибка: "result": false и текст в "message".

Не больше 120 запросов в минуту. Число сегментов зависит от тарифа.

Задача	Адрес
Список сегментов	`/v1/bot/group/index`
Сколько сегментов	`/v1/bot/group/count`
Создать по условию	`/v1/bot/group/create-from-preset`
Создать из списка пользователей	`/v1/bot/group/create-with-users`
Создать пустой	`/v1/bot/group/create`
Узнать размер аудитории без создания	`/v1/bot/group/preset-user-ids`
Список людей в сегменте	`/v1/bot/group/group-user/index`
Сколько людей в сегменте	`/v1/bot/group/group-user/count`
Добавить человека	`/v1/bot/group/group-user/create`
Убрать человека	`/v1/bot/group/group-user/delete`
«Все, кроме этого сегмента»	`/v1/bot/group/inverse`
Удалить сегмент	`/v1/bot/group/delete`

Адрес: /v1/bot/group/create-from-preset

Передайте название, тип условия и параметры.

Пример. Активные за последние 30 дней:

{
  "bot_id": 1,
  "title": "Активные за 30 дней",
  "preset": "active_days",
  "params": { "days": 30 }
}

В ответе придут ID сегмента, название и сколько людей попало внутрь.

Если под условие никто не подходит, сегмент не создаётся — придёт сообщение об ошибке.

Условие (`preset`)	Что нужно указать	Кого отбирает
`active_days`	`days` — число дней (1–730)	Писали боту за этот срок
`registered_days`	`days`	Зарегистрировались за этот срок
`shop_orders_min`	`min` — минимум заказов	Заказы в магазине
`cart_orders_min`	`min`	Оплаченные заказы в корзине
`subscriber_orders_min`	`min`	Заказы по подписке
`payment_orders_min`	`min`, опционально ID сообщения	Успешные оплаты в боте
`balance_min`	`amount` — сумма в рублях (или вашей валюте)	Баланс не меньше суммы
`balance_ops_min`	`count`	Не меньше стольких операций с балансом
`has_referrer`	—	Есть пригласивший
`referrals_min`	`count`	Не меньше стольких рефералов
`referrals_topped_up_min`	`count`	Рефералы, которые пополняли баланс
`script_cyrillic`	—	Имя на кириллице
`script_arabic`	—	Имя на арабском
`script_cjk`	—	Имя на китайском / японском / корейском

Для заказов и оплат считается число покупок, не сумма.
Для баланса указывайте обычную сумму (например 100), не копейки.

Ещё примеры:

Покупатели с 3 и более заказами:

{
  "bot_id": 1,
  "title": "От 3 заказов",
  "preset": "shop_orders_min",
  "params": { "min": 3 }
}

Баланс от 100:

{
  "bot_id": 1,
  "title": "Баланс от 100",
  "preset": "balance_min",
  "params": { "amount": 100 }
}

Адрес: /v1/bot/group/preset-user-ids

Те же preset и params, но сегмент не создаётся — только число людей и их ID.

Удобно проверить «сколько человек попадёт», и уже потом создавать сегмент.

Адрес: /v1/bot/group/create-with-users

Нужны название и список ID пользователей в боте (не Telegram ID).

{
  "bot_id": 1,
  "title": "Моя аудитория",
  "bot_user_ids": [101, 102, 103]
}

Как узнать ID в боте по Telegram ID: запрос /v1/bot/user/view-by-telegram-id — в ответе поле id.

Адрес: /v1/bot/group/group-user/index

Передайте ID сегмента. Можно листать: до 100 записей за раз (limit), следующая страница — через offset.

{
  "bot_id": 1,
  "group_id": 42,
  "limit": 100,
  "offset": 0
}

У каждого человека в ответе есть Telegram ID — в блоке пользователя, поле telegram_id.
Сколько всего в сегменте: /v1/bot/group/group-user/count.

Добавить — /v1/bot/group/group-user/create
Нужны ID сегмента и системный ID пользователя.

Убрать — /v1/bot/group/group-user/delete
Нужен ID записи из списка людей сегмента (можно несколько сразу).

Действие	Что происходит
Пустой сегмент (`/v1/bot/group/create`)	Только название, людей пока нет
Обратный сегмент (`/v1/bot/group/inverse`)	Все, кого нет в выбранном сегменте
Удаление (`/v1/bot/group/delete`)	Можно удалить один или несколько сегментов

Проверить размер аудитории (preset-user-ids или /v1/common/link-track/users-count).
Создать сегмент по условию (create-from-preset) или по действиям (/v1/common/link-track/create-segment).
При необходимости выгрузить Telegram ID (group-user/index).
Использовать сегмент в рассылке.