bots:creating

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

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

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

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

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

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

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

Здесь в строке Статус также можно поставить бота на паузу.

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

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

Если восстановить заблокированного пользователя-бота, все настройки восстановятся в том виде, какими они были до блокировки. Можно блокировать и восстанавливать бота сколько угодно раз, ограничений нет.

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

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

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

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

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

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

POST-запрос

  • Тело.
    task — задача в формате Pyrus API.
    task_id — задача, на которой сработало событие. См. подробное описание структуры.
    access_token — токен для вызова Pyrus API. Время жизни токена — 5 минут. За это время бот сразу возвращает код 200 без комментария, идет во внешнюю систему и делает нужные вычисления. Это может занимать до 5 минут. Затем бот делает запрос на добавление комментария в задачу через PublicAPI с этим токеном.

{
  "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) не нужно.

Была ли эта статья полезной?

Да, спасибо! Нет, остался вопрос