Мы пока тестируем ботов, но уже можем дать к ним доступ. Пишите нам, если боты вам нужны.

Этот раздел адресован разработчикам приложений. Для настройки бота Pyrus вам потребуются навыки программирования и работы с Pyrus API.

Когда вам нужно получать информацию из Pyrus для другой системы, приложения или программы, часто решением становится Pyrus API. С его помощью вы делаете запрос и в ответ получаете из Pyrus нужные данные. Однако, если использовать Pyrus API для настройки уведомлений об изменении статуса задачи или этапа работы с ней, придется периодически делать одинаковые API-запросы к Pyrus, чтобы узнать о нужном событии. Такой способ сложно назвать оптимальным.

Здесь на помощь приходят боты Pyrus, виртуальные пользователи системы, которых можно назначать ответственными и согласующими процессов, проектов и задач. Когда задача приходит к боту, Pyrus сообщает об этом вашей программе. То есть уже вашей программе в нужный момент приходит запрос от Pyrus, а не приложение постоянно «опрашивает» систему.

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

Важно учитывать два ограничения:

• ответственным в задаче после бота не может быть другой бот (система не позволит вам так сделать);
• на одном этапе маршрута не могут быть два бота.

Организация может завести до 100 ботов, число вызовов бота не ограничено. Условия оплаты аккаунта бота те же, что и для других аккаунтов сотрудников. Но аккаунт бота — специального вида, создать его можно на вкладке Bots в разделе User Managment. Он числится как неактивированный пользователь.

Для работы с ботами вам нужно право настраивать интеграции и редактировать справочники в Pyrus.

У каждого бота есть название, которое выбираете вы. В качестве логина генерируется уникальный несуществующий адрес электронной почты. Из-под учетной записи бота можно делать вызовы API. Авторизоваться в системе, используя логин бота, нельзя.

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

Бот отправляет HTTPS-запросы методом POST. На запрос бота ваш сервер должен ответить статусом 2XX в течение 60 секунд после вызова. Если сервер недоступен или отвечает любым другим статусом, Pyrus отправит второй запрос через 61 секунду, а затем третий — через 122 секунды. Номер попытки виден в дополнительном заголовке запроса.

Конфигурация бота состоит из адреса для вызовов ( URL ), параметров Security Key, ClientId и свойства включен/выключен.

URL — адрес страницы на вашем сайте. На этой странице должен располагаться код обработчика событий. Когда задача переходит к боту, Pyrus делает запрос по этому адресу. Разрешены только HTTPS-адреса.

Требования к сертификату: сертификат HTTPS должен быть проверяем. Цепочка сертификатов должна прослеживаться до известного удостоверяющего центра.

Security Key и ClientId генерируются автоматически при создании бота и нужны для вызовов API. Ключ Security Key используется для подписи каждого вызова и гарантирует, что вызовы делаются от имени Pyrus.

• Тело. Полное описание TaskNote. Структура как элемент массива Notes в объекте TaskWithNotes, который возвращает метод API GetTask с дополнительными свойствами в Json-объекте Note: UserId (идентификатор пользователя-бота) и TaskId — задача, на которой сработало событие. См. подробное описание структуры.
• Юзерагент Pyrus-Bot-3. Здесь цифра 3 – версия протокола (совпадает с версией Public API).
• Дополнительный заголовок X-Pyrus-Sig. Значение — подпись строки URL ключом Security Key, в hex-виде. Она вычисляется как HMAC-дайджест с использованием алгоритма SHA1 для хеширования.
• Дополнительный заголовок X-Pyrus-Retry. Значение — одно из трех: «1/3», «2/3» или «3/3». В числителе номер попытки, начиная с единицы, а в знаменателе — количество попыток (три попытки). Для первого вызова, который не является повтором, значение ставится «1/3».

При необходимости можно указать тело ответа. Тело ответа повторяет структуру запроса Public API CreateComment. Указывать авторизационный заголовок (Header Authorization) не нужно.