Боты

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

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

Все методы раздела возвращают объект бота в формате, описанном ниже.

Методы

• GET/botsПолучение списка ботов организации
• POST/botsСоздание бота
• PUT/bots/{id}Изменение бота
• DELETE/bots/{id}Удаление бота

GET /bots

Метод возвращает список ботов организации. По умолчанию удалённые боты в список не попадают — чтобы получить и их, передайте параметр include_fired=true.

GET https://api.pyrus.com/v4/bots?include_fired=false

{
  "bots": [
    {
      "id": 1234567,
      "name": "Support bot",
      "is_enabled": true,
      "hook_url": "https://example.com/pyrus-hook",
      "description": "Отвечает на обращения клиентов",
      "bot_settings": "{\"mode\":\"prod\"}",
      "version": 4,
      "login": "bot@8f1b0c1e-3f7a-4d2b-9d7e-2b1f3a9c6e11",
      "external_id": "crm-42",
      "send_only_last_comment": false,
      "time_zone_offset": 180,
      "locale": "ru-RU",
      "avatar_id": 98765
    }
  ]
}

curl -X GET \
  'https://api.pyrus.com/v4/bots?include_fired=false' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Параметры

Поля ответа

Объект бота имеет одинаковый формат во всех методах раздела. Пустые поля в ответе не возвращаются.

POST /bots

Метод создаёт бота в организации пользователя и возвращает его.

Новый бот сразу включён. Локаль бота совпадает с локалью пользователя, который его создал. Описание, настройки, часовой пояс, локаль и другие параметры можно задать после создания методом PUT /bots/{id}.

POST https://api.pyrus.com/v4/bots

{
  "name": "Support bot",
  "hook_url": "https://example.com/pyrus-hook",
  "external_id": "crm-42"
}

{
  "id": 1234567,
  "name": "Support bot",
  "is_enabled": true,
  "hook_url": "https://example.com/pyrus-hook",
  "version": 4,
  "login": "bot@8f1b0c1e-3f7a-4d2b-9d7e-2b1f3a9c6e11",
  "external_id": "crm-42",
  "send_only_last_comment": false,
  "locale": "ru-RU"
}

curl -X POST \
  https://api.pyrus.com/v4/bots \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Support bot",
    "hook_url": "https://example.com/pyrus-hook",
    "external_id": "crm-42"
  }'

Параметры

PUT /bots/{id}

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

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

PUT https://api.pyrus.com/v4/bots/1234567

{
  "name": "Support bot v2",
  "hook_url": "https://example.com/pyrus-hook-v2",
  "is_enabled": true,
  "bot_settings": "{\"mode\":\"prod\"}",
  "description": "Отвечает на обращения клиентов",
  "send_only_last_comment": true,
  "time_zone_offset": 180,
  "locale": "ru"
}

{
  "id": 1234567,
  "name": "Support bot v2",
  "is_enabled": true,
  "hook_url": "https://example.com/pyrus-hook-v2",
  "description": "Отвечает на обращения клиентов",
  "bot_settings": "{\"mode\":\"prod\"}",
  "version": 4,
  "login": "bot@8f1b0c1e-3f7a-4d2b-9d7e-2b1f3a9c6e11",
  "external_id": "crm-42",
  "send_only_last_comment": true,
  "time_zone_offset": 180,
  "locale": "ru-RU"
}

curl -X PUT \
  https://api.pyrus.com/v4/bots/1234567 \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "is_enabled": false,
    "description": "Временно отключён"
  }'

Параметры

DELETE /bots/{id}

Метод удаляет бота из организации и возвращает его с полем "fired": true. Задачи, в которых участвовал бот, передаются сотруднику, указанному в запросе.

DELETE https://api.pyrus.com/v4/bots/1234567

{
  "task_receiver_id": 7654321
}

{
  "id": 1234567,
  "name": "Support bot",
  "is_enabled": true,
  "hook_url": "https://example.com/pyrus-hook",
  "version": 4,
  "login": "bot@8f1b0c1e-3f7a-4d2b-9d7e-2b1f3a9c6e11",
  "external_id": "crm-42",
  "send_only_last_comment": false,
  "locale": "ru-RU",
  "fired": true
}

curl -X DELETE \
  https://api.pyrus.com/v4/bots/1234567 \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_receiver_id": 7654321
  }'

Параметры