Отправка и запуск

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

Авторизация

Права: messages:send для отправки, chains:write для запуска цепочек и блоков.

---

Отправить сообщение

POST /message/send

curl -X POST https://api.quescha.com/api/message/send \
  -H "Authorization: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{
    "botid": "123456789",
    "clientid": "987654321",
    "text": "Заказ A-1024 собран и передан в доставку",
    "buttons": [{"name": "Отследить", "url": "https://example.com/track/A-1024"}]
  }'

Поле	Обязательный	Описание
botid, clientid	Да	кому пишем
text	Да*	текст сообщения
buttons	Нет	массив кнопок-ссылок [{name, url}]

* можно без текста, если переданы кнопки.

{ "ok": true, "sent": 1 }

Сообщение попадает в переписку подписчика — его видно на странице «Общение», как и любое другое.

Кнопки только ссылками

Наружу отдаются кнопки-ссылки. Кнопка, ведущая на блок бота, требует знания устройства бота — для этого есть метод /block/start, он делает то же самое надёжнее.

Когда бот не сможет написать

Подписчик отключён (subscriber_off) или заблокировал бота (subscriber_blocked) — придёт ответ 409. В Телеграме и других мессенджерах бот не может написать первым тому, кто сам не начинал диалог, — это ограничение площадки.

---

Запустить цепочку

POST /chain/start

Ставит подписчика на первый шаг цепочки. Дальше она идёт сама — по своим настройкам времени.

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

Поле	Обязательный	Описание
chaincode	Да	код цепочки, берётся из /chain/list
data	Нет	переменные, которые увидит сценарий как #{имя}

Цепочка должна быть включена: запуск выключенной стёр бы прогресс подписчика, поэтому придёт ошибка chain_off.

---

Запустить конкретный блок

POST /block/start

То же самое, что кнопка «Запустить с этого блока» в редакторе. Подходит, когда нужно не начало воронки, а её середина — например, показать экран «Ваш заказ готов».

Поле	Обязательный	Описание
chaincode	Да	код цепочки
stepcode	Да	код шага, берётся из /chain/steps
block	Нет	номер блока с единицы или его ID; пусто — первый блок
data	Нет	переменные для сценария

{ "ok": true, "chain": "Заказы", "step": "Готовность", "block": "Сообщить клиенту" }

Шаг должен быть сценарием действий — у обычного шага блоков нет (not_scenario).

---

Остановить цепочку

POST /chain/stop

С параметром chaincode останавливает одну цепочку, без него — все. В ответе stopped — сколько остановлено.

---

Рассылка по сегменту

POST /broadcast/send

Ставит сообщение в ту же очередь, что и страница рассылок в кабинете: отправка идёт по одному сообщению в секунду — иначе мессенджер отобьёт пачку.

curl -X POST https://api.quescha.com/api/broadcast/send \
  -H "Authorization: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{
    "text": "Завтра открываем запись на сентябрь",
    "tag": ["клиент"],
    "botid": "123456789",
    "name": "Анонс сентября"
  }'

Поле	Описание
text, buttons	что рассылаем
botid	только подписчикам одного бота
tag	тег или массив тегов: кому
dialog	true — только начавшим диалог
blocked	true — включить и заблокированных (по умолчанию они пропускаются)
name	название рассылки, видно в кабинете

{ "ok": true, "planned": 842, "code": "839201748293011" }

code пригодится, чтобы отменить рассылку:

POST /broadcast/stop с параметром code снимает все запланированные отправки, которые ещё не ушли.

Рассылки входят не во все тарифы

Если рассылки не включены в тариф, придёт ответ 403 tariff. Это та же проверка, что и в кабинете.

---

Отменить отложенный запуск

POST /message/next/clear

Прекращает отложенный запуск следующего сообщения у конкретного подписчика. Полезно, если по ходу сценария нужно отменить ранее запланированную отправку.

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

{ "result": "cleared" }