API сервиса BotMan.pro открывает разработчикам и техническим специалистам возможность гибко управлять ботами, интегрировать их с внешними системами и строить сложные сценарии без вмешательства в пользовательский интерфейс.
Авторизация
Для работы с API необходимо получить персональный токен доступа в разделе «Интеграции» личного кабинета. Все последующие запросы отправляются с этим токеном в заголовке Authorization. Токен одноуровневый и даёт права на чтение и изменение всех ботов указанного аккаунта.
Управление ботами
Метод «Список ботов» возвращает перечень всех проектов с идентификаторами, названиями и статусом публикации. По полученному ID можно получить детальную информацию о конкретном боте: подключённые каналы (Telegram, VK), число подписчиков и дату последнего обновления. Это удобно для мониторинга «здоровья» сразу нескольких проектов в одном скрипте.
Создание и обновление сценариев
API позволяет программно добавлять блоки сценария, устанавливать связи между ними и редактировать содержимое. Например, можно создать новый текстовый блок со вступительным сообщением, сразу задать условия ветвления по ключевым словам и привязать к нему кнопку с переходом на следующий этап. Все операции с блоками выполняются через единый метод «Редактирование сценария»: передаётся массив операций — создание, обновление или удаление — и в ответ приходит обновлённая структура.
Рассылки и планирование отправки
Для отправки массовых и триггерных рассылок используется метод «Рассылка». В запросе указываются ID рассылки, целевая аудитория (список тегов или фильтр по переменным) и время запуска. Можно задать отложенный запуск в виде временной метки или запустить рассылку немедленно. В ответ API возвращает планировщик с предстоящими задачами, которые при необходимости можно отменить или перенастроить.
Работа с вебхуками
Для обработки входящих сообщений и событий внутри бота используют вебхуки. Метод «Настройка вебхука» позволяет указать публичный URL, на который сервис будет отправлять уведомления о новых сообщениях, оплатах и изменениях в профиле пользователя. В теле каждого уведомления приходит структура с ID пользователя, ID бота и типом события, что упрощает интеграцию с CRM и аналитическими системами в реальном времени.
Отправка сообщений вручную
Иногда требуется адресно отправить сообщение конкретному пользователю по результатам внешнего события (например, статуса заказа). Для этого существует метод «Push-сообщение»: в запросе нужно передать ID пользователя, ID бота, тип и текст сообщения, а также дополнительные параметры — кнопки, вложения или клавиатуру. Сообщение поступает мгновенно без участия шаблонов сценария.
Получение статистики
API статистики предоставляет метрики по каждому блоку: число показов, переходов по кнопкам, процент прохождения ветвлений и конверсию в оплату. Обращаясь к методу «Метрики бота», можно получить данные за произвольный период в виде JSON-объекта с разбивкой по дням. Это удобно для построения собственных дашбордов или передачи данных в BI-систему.
Управление пользователями
Метод «Список пользователей» возвращает всех подписчиков бота с актуальными переменными (имя, телефон, теги и пр.). Для каждого пользователя доступен отдельный метод «Профиль пользователя», где можно изменять теги или переменные на лету. Это позволяет корректировать путь прохождения автоворонки из внешних систем или обновлять данные после офлайн-событий.
Обработка платежей
После интеграции платёжных шлюзов через интерфейс конструктора, API оповещает о событиях «Платёж успешно» и «Платёж отменён» через вебхук. Кроме того, метод «Поиск транзакций» позволяет получить историю платежей за нужный период, фильтровать по сумме и статусу, а также запускать дополнительные проверки по ID заказа.
Пример сценария интеграции
Допустим, система CRM прислала уведомление о попытке клиента сменить тариф. Ваш сервис получает вебхук, обрабатывает его и делает запрос к API BotMan.pro, чтобы изменить переменную пользователя «тариф» на новый. Затем через метод «Push-сообщение» бот отправляет клиенту персональное уведомление: «Ваш тариф обновлён. Спасибо за выбор!». Вся цепочка управляется внешним кодом без ручного правления сценариев.
Ошибки и отладка
При некорректных запросах API возвращает подробные сообщения об ошибке: неверный токен, отсутствие прав, несуществующий ID или нарушение валидации. Рекомендуется обрабатывать коды ответа HTTP и логировать тело ошибок для быстрой отладки и гарантии надёжности интеграции.
API BotMan.pro сочетает простоту управления ботами через «цепочку» REST-запросов и гибкость построения сложных сценариев на стороне внешних систем. Грамотное использование методов ускоряет запуск автоворонок, упрощает масштабирование проектов и обеспечивает сквозной контроль за взаимодействием с клиентами.
При написании статьи частично задействована информация с сайта botman.pro — API сервиса чат-ботов
Дата публикации: 21 апреля 2022 года
