bots:creating

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

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

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

Чтобы создать бота, нажмите Добавить нового бота.

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

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

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

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

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

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

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

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

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

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

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

Конфигурация бота состоит из адреса для вызовов (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) не нужно.

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

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