Как создать бота

Важно: создавать ботов может пользователь с правами Управляющего интеграциями и/или Администратора.

Чтобы настроить бота, перейдите в раздел Боты.

Нажмите Добавить бота в верхней панели справа.

В открывшемся окне задайте конфигурацию бота:

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

Нажмите Добавить.

Pyrus сформирует параметры нового бота и покажет их во всплывающем окне:

• Логин — логин для бота в формате bot@<guid>.
• Секретный ключ нужен для вызовов API — используется для подписи каждого вызова и гарантирует, что вызовы делаются от имени Pyrus.

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

Здесь боту можно задать Дополнительные права. Права Управляющего подойдут, если нужен доступ к редактированию справочников. Права Руководителя понадобятся для сбора статистики через приложение Pyrus Sync.

Параметры сценария для бота можно задать в поле Настройки прямо в его профиле. Это может быть текст смс или электронного письма, которое он будет отправлять при определённом событии, имя поля формы или, например, JSON-объект.

Для детальной настройки бота можно указать следующие данные.

1. Часовой пояс бота для получения из задачи полей с датой и временем в соответствии с часовым поясом.

2. Локаль бота, от которой зависят некоторые параметры отображения форматов дат.

3. Данные, передаваемые при вызове бота. С помощью этой настройки можно выбрать, передавать все комментарии вместе с задачей или только последний комментарий. Настройка поможет сократить объем траффика, когда комментариев становится слишком много.

Поставить бота на паузу можно, просто передвинув переключатель в положение Отключено.

В строке Секретный ключ можно изменить значение ключа безопасности — для этого нажмите Сбросить. Это нужно, если вы подозреваете, что текущий ключ безопасности скомпрометирован. После сброса ключа злоумышленник не сможет получить новый токен со старым ключом. При этом настроенные раньше боты будут работать, как и прежде.

Также в профиле бота вы можете отслеживать отклонения его действий от заданного сценария — ошибки. Они отображаются в Журнале событий внизу страницы.

Если нужно заблокировать бота, нажмите Удалить в профиле. При удалении бот пропадает из списка, а соответствующий ему неактивированный пользователь блокируется (его можно будет видеть в списке Заблокированы в разделе Пользователи).

Конфигурация бота

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

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

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

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

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

POST-запрос

• Тело.

  task — задача, в которой произошло событие. Формат этого поля совпадает с ответом API-запроса получения задачи.

  task_id — номер задачи, в которой произошло событие. См. подробное описание структуры.

  access_token — авторизационный токен. В течение 5 минут после вызова бот может выполнять запросы к Pyrus через PublicAPI, используя access_token для авторизации. Если на обработку вызова бота требуется больше 30 секунд, мы рекомендуем сразу вернуть код 200 без тела запроса, а по окончании вычислений создать комментарий в задаче, отправив запрос на добавление комментария через PublicAPI с использованием access_token.

  {
    "task_id":5600,
    "task":{/* task with comments */},
    "access_token":"{token}"
  }
  

• Заголовок User-Agent Pyrus-Bot-4. Здесь цифра 4 – версия протокола (совпадает с версией Pyrus API).

• Дополнительный заголовок X-Pyrus-Sig. Значение — строка, содержащая подпись сообщения для проверки того, что вызов бота выполнил Pyrus, а не кто-то другой. Для проверки подписи необходимо к телу запроса добавить секретный ключ и вычислить для получившейся строки HMAC-дайджест с использованием алгоритма SHA1. Смотрите реализацию проверки подписи на Python.

• Дополнительный заголовок X-Pyrus-Retry. Значение — одно из трех: «1/3», «2/3» или «3/3». В числителе номер попытки, начиная с единицы, а в знаменателе — количество попыток (три попытки). Для первого вызова, который не является повтором, значение ставится «1/3».

Ответ: HTTP 2XX

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