integration:bots

СКОРО

Боты Pyrus

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

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

Для чего нужны боты

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

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

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

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

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

Как завести бота Pyrus

Организация может завести до 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.

Структура данных

POST-запрос

  • Тело. Полное описание 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».

Ответ: HTTP 2XX

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

Возникли вопросы? Мы всегда рядом, чтобы помочь.

СВЯЖИТЕСЬ С НАМИ

8 800 555-69-55
бесплатно по России

+7 495 980-13-11
для звонков из других стран