Подписчики

Методы для работы с базой подписчиков: карточка, поиск, список, теги, переменные, блокировка и удаление.

Авторизация

Все запросы требуют API-ключа — см. Авторизация. Права: subscribers:read для чтения, subscribers:write для изменений.

---

Как указать подписчика

Почти все методы принимают одну и ту же пару параметров:

Поле	Тип	Обязательный	Описание
botid	string	Да	BotID бота. Смотрите /bot/list
clientid	string	Да	ClientID подписчика в этом боте
messenger	string	Нет	Уточняет мессенджер, если один и тот же BotID заведён дважды

Есть два запасных пути:

• subscriber — внутренний номер карточки, его отдают методы списка и поиска. Заменяет собой все три параметра выше.
• messenger + clientid без botid — если в аккаунте ровно один бот этого мессенджера. Так устроены бот-лендинг и Живосайт: BotID у них нет вовсе. Если ботов несколько, придёт ошибка many_bots.

Названия мессенджеров

telegram, max, wa (WhatsApp), wabusiness (WhatsApp Business), viber, vk, jivo, lp (бот-лендинг и сайт), avito, instagram, wb (Wildberries), ozon, cian, tiktok, fb, yandexmarket, discord.

Принимаются и привычные написания: tg, телеграм, вк, whatsapp, макс, авито.

---

Карточка подписчика

GET|POST /subscriber/get

curl "https://api.quescha.com/api/subscriber/get?botid=123456789&clientid=987654321" \
  -H "Authorization: ВАШ_КЛЮЧ"

{
  "subscriber": {
    "id": 4211,
    "clientid": "987654321",
    "messenger": "telegram",
    "botid": "123456789",
    "name": "Пётр Иванов",
    "username": "petr",
    "tags": ["Этап: Новый", "vip"],
    "note": "звонить после 18",
    "active": true,
    "blocked": false,
    "subscribed": true,
    "dialog": true,
    "balance": 0,
    "created": "2026-08-01T10:12:00.000Z",
    "chain": "483920174829301",
    "step": "718239104829301"
  }
}

Поля chain и step показывают, где подписчик находится в воронке прямо сейчас.

---

Поиск

GET|POST /subscriber/find

Ищет по имени, нику, ClientID и заметке. Телефон и почта отдельными колонками не хранятся: в конструкторе они попадают в список или в заметку — поэтому поиск по заметке и находит номер, сохранённый туда.

Поле	Обязательный	Описание
query	Да*	что искать; часть значения тоже подойдёт
tag	Да*	точный тег — можно вместо query
botid	Нет	искать только в одном боте
limit, offset	Нет	постранично

* нужен хотя бы один из двух.

---

Список с фильтрами

GET|POST /subscriber/list

Поле	Описание
botid, messenger	только один бот или один мессенджер
tag	у кого есть этот тег
active, blocked, dialog	true или false
from, to	дата подписки, 2026-08-01 или ISO
sort	new (по умолчанию) или old
limit, offset	постранично; в ответе есть total

{ "items": [ … ], "total": 1024, "limit": 50, "offset": 0 }

---

Создание и правка

POST /subscriber/create — заводит карточку или обновляет существующую. Нужно при переносе базы из другой системы: карточки заводятся заранее, а бот подхватит их, когда человек напишет.

Первым написать может не бот, а человек

Карточка в базе не даёт права написать подписчику первым — это ограничение мессенджера, а не конструктора. В Телеграме бот может ответить только тому, кто сам начал диалог.

POST /subscriber/update — меняет name, username и note.

---

Теги

POST /subscriber/tag/add и POST /subscriber/tag/remove

curl -X POST https://api.quescha.com/api/subscriber/tag/add \
  -H "Authorization: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"botid":"123456789","clientid":"987654321","tag":["оплатил","vip"]}'

Тег можно передать строкой или массивом. В ответ приходит полный список тегов.

Теги запускают цепочки

Тег ставится ровно так же, как это делает бот: если у цепочки в настройках стоит запуск по этому тегу — она запустится, а если тег стоп-тегом, цепочка остановится. Поле chains: true в ответе означает, что обработка тегов прошла.

GET|POST /subscriber/tag/list — только теги, без остальной карточки.

---

Переменные подписчика

POST /subscriber/data/set — записать значения, которые увидит сценарий действий как #{имя}.

curl -X POST https://api.quescha.com/api/subscriber/data/set \
  -H "Authorization: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"botid":"123456789","clientid":"987654321","data":{"номер_заказа":"A-1024","сумма":"3500"}}'

Переменные живут внутри цепочки

У каждой запущенной цепочки свой набор переменных — так устроен движок. Без параметра chaincode значения запишутся во все запущенные цепочки подписчика, с ним — только в одну.

Если у подписчика не запущено ни одной цепочки, придёт ошибка no_active_chain: переменной негде жить. Сначала запустите цепочку методом /chain/start — ему можно передать data сразу.

GET|POST /subscriber/data/get — что сейчас лежит в переменных, по цепочкам.

---

Блокировка

POST /subscriber/block и POST /subscriber/unblock

Заблокированный подписчик не получает рассылок и сообщений. Блокировка обратима — в отличие от удаления.

---

Переписка и цепочки

GET|POST /subscriber/chat/get — история сообщений:

{ "items": [ { "id": 91, "from": "client", "text": "Здравствуйте", "at": "…" } ] }

from — client или bot.

GET|POST /subscriber/chains/get — в каких цепочках подписчик, на каком шаге и когда следующая отправка.

---

Удаление подписчика

POST /subscriber/delete

Операция необратима

Удалятся все данные подписчика в боте — переписка, теги, добавленные данные. Если нужно просто перестать писать человеку, используйте /subscriber/block.

Поле	Тип	Обязательный	Описание
clientid	number | string	Да	ClientID подписчика
messenger	string	Да	мессенджер подписчика
botid	string	Да	BotID бота

{ "result": "Subscriber successfully deleted" }