Перейти на сайт

События из вашей системы: сообщения по оплате, корзине, уроку

Как сайт, CRM или сервис оплаты сообщает Botman о событии и где событие запускает сценарии, авторассылки и фильтры.

Статья для тех, у кого есть сайт, CRM, онлайн-школа или сервис оплаты и кто хочет, чтобы бот написал человеку в нужный момент: сразу после оплаты, когда он бросил корзину, когда открылся новый урок. Ваша система одним запросом сообщает Botman, что произошло, а что и когда отправить — вы настраиваете в кабинете без кода.

Что такое событие

Событие — это запись «с этим человеком произошло вот это». У него есть имя (например, order_paid), способ найти подписчика (email, телефон, ID подписчика или ваше поле) и данные — сумма, номер заказа, название курса.

Как прислать событие

  1. Откройте «Интеграции» → вкладку «API». Нажмите «Выпустить ключ» и скопируйте его.
  2. Отправьте запрос POST на адрес https://api.botman.pro/public/api/v1/events, ключ — в заголовке X-Api-Key.
curl -X POST 'https://api.botman.pro/public/api/v1/events' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "event": "order_paid",
  "contact": { "email": "anna@example.com" },
  "properties": { "amount": 4900, "order_id": "A-1042" },
  "idempotencyKey": "order_paid-1042"
}'
  • event — имя события: латинские буквы в нижнем регистре, цифры, «_» и «.», до 64 символов. Имена на botman. заняты событиями самого Botman.
  • contact — как найти подписчика, ровно один способ: email, phone, subscriberId или своё поле customField — {"id": "ID поля", "value": "A-17"}.
  • properties — данные события, необязательно. До 50 ключей и не больше 4 КБ. Ключ — латиница в нижнем регистре, цифры и «_», до 40 символов. Значение — строка, число или true/false. Ключи name и occurred_at заняты.
  • occurredAt — когда событие произошло, например 2026-11-07T12:00:00Z. Не указали — время приёма.
  • idempotencyKey — свой у каждого события, до 128 символов. Если запрос с тем же ключом придёт повторно в течение 30 дней, сценарий второй раз не запустится.

Что вернёт Botman

{
  "eventId": "...",
  "status": "MATCHED",
  "matched": [ { "subscriberId": "...", "channelId": "...", "platform": "TELEGRAM" } ]
}
  • MATCHED — подписчик найден. Сценарии запускаются по каждому найденному.
  • UNMATCHED — подписчик не найден. Событие сохранено и ждёт его (см. ниже).
  • DUPLICATE — событие с этим idempotencyKey уже принято, повтор не обрабатывается. В ответе — eventId первого события.

Несколько событий одним запросом

POST /public/api/v1/events/batch с телом {"events": [ ... ]} — до 100 событий. Ответ — итог по каждому событию в том же порядке. Событие с ошибкой получает статус REJECTED и причину в error, остальные принимаются.

Какие события уже приходили

GET /public/api/v1/events/catalog — имена событий аккаунта: когда событие пришло впервые и в последний раз, сколько раз и какие ключи данных у него были.

Как Botman находит человека

  • Ищет среди подписчиков всех каналов вашего аккаунта.
  • Email сравнивается без учёта регистра. Телефон — в нескольких записях: как есть, только цифры, с «+» и в международном формате.
  • Один email бывает у подписчиков в разных каналах — тогда найдутся все (до 20). В триггере можно выбрать, запускать сценарий всем или только в одном канале.
  • ID подписчика есть в его карточке: «Профиль» → «Служебное» → «ID подписчика». ID своего поля возвращает метод GET /public/api/v1/customFields.

Если подписчика ещё нет

Человек мог оплатить на сайте раньше, чем пришёл в бота. Событие подождёт его 7 дней: как только появится подписчик с тем же email, телефоном или значением своего поля, событие применится к нему — запустятся сценарии, а в журнале запросов у события будет отметка «Найден позже». Событие с поиском по subscriberId не ждёт.

Не отправляйте такое событие повторно с тем же idempotencyKey: в течение 30 дней ответ будет DUPLICATE, и подписчик заново искаться не будет.

Где работают события

  • Сценарии — триггер «Событие из API» в начальном шаге запускает сценарий. Подробнее — в статье «Триггер «Событие из API»».
  • Шаг «Ждать событие» — сценарий ждёт, например, оплату не дольше 2 часов и идёт по ветке «Событие пришло» или «Не пришло за …». Подробнее — в статье «Шаг «Ждать событие»: брошенная корзина и дожим оплаты».
  • Авторассылки — условие «Было событие»: сообщение придёт, как только событие появится у подписчика. Условие «Не было события»: сообщение придёт через выбранное число дней, от 3 до 150. Его Botman проверяет раз в день и считает дни с последнего такого события; у кого события не было ни разу, сообщение не получит.
  • Подписчики — фильтр «По событию»: «Было» или «Не было», «За период» (число дней) или «За всё время». Набор условий можно сохранить как группу и выбрать её аудиторией рассылки.
  • Карточка подписчика — вкладка «История»: события из вашей системы и события Botman, а по каждому — что запустилось.

В авторассылках и фильтре, кроме ваших событий, есть события Botman: «Подписался на бота», «Получил метку», «Сняли метку», «Изменилось поле», «Оплатил». Они записываются с даты запуска функции, более ранних нет.

Журнал запросов

«Интеграции» → «API» → «Журнал запросов» — все запросы к API за последние 7 дней. Фильтры: «Все запросы», «События», «Требуют внимания» (только запросы с ошибкой). Нажмите на строку — откроются ответ, время ответа, номер запроса и для события блок «Что произошло»: как искали подписчика, кого нашли, какой сценарий запущен или почему нет.

Ограничения

  • В одном запросе пачкой — до 100 событий.
  • Данные события — до 50 ключей и 4 КБ.
  • Повтор с тем же idempotencyKey распознаётся 30 дней.
  • Событие ждёт подписчика 7 дней.
  • Журнал запросов хранит запросы 7 дней, история событий подписчика — 180 дней.
  • Триггер «Событие из API» недоступен в каналах TikTok.

Частые ошибки

  • 401 или 403 — ключ не подошёл. Проверьте заголовок X-Api-Key. После «Выпустить новый» старый ключ сразу перестаёт работать.
  • 422, CRM-287 — имя события не по формату: заглавные буквы, кириллица, пробел. CRM-288 — имя начинается с botman..
  • 422, CRM-289 — данные события: больше 50 ключей или 4 КБ, значение-список или вложенный объект, ключ name или occurred_at.
  • 422, CRM-290 — в contact не указан способ поиска или указано несколько сразу.
  • 422, CRM-291 — своё поле для поиска не найдено. Проверьте ID поля.
  • 429 — слишком много запросов подряд. Отправляйте реже или пачкой.
  • 503 — событие не записано. Повторите запрос через время из заголовка Retry-After с тем же idempotencyKey.
  • Ответ MATCHED, но сообщения нет — откройте событие в журнале запросов: в «Что произошло» видна причина, например «Нет включённых сценариев с этим событием» или «данные события не подошли под условия».
  • Авторассылка «Было событие» не пришла — проверьте occurredAt: по событиям, которые произошли больше 6 часов назад, авторассылка не отправляется.
👆 На этом пока всё