Bots

Cloud Pyrus

Cloudless Pyrus

A bot is a technical Pyrus user that does not work through the web or mobile app but processes tasks automatically. When a task is routed to a bot, Pyrus sends a POST request to the handler URL specified in the bot settings and performs the actions returned by the handler. You can find more information about how bots work in the help section.

The methods in this section let you get a list of the organization's bots and create, update, and delete bots without opening the Pyrus web interface. For example, this is useful when you need to deploy identical bots in several organizations or manage bots from an external system.

Note: to call these methods, you need a token of a user with Configuration Manager rights. An existing bot can also be updated by its administrator.

All methods in this section return a bot object in the format described below.

Methods

GET/botsGet the list of organization bots
POST/botsCreate bot
PUT/bots/{id}Update bot
DELETE/bots/{id}Delete bot

GET /bots

This method returns a list of the organization's bots. Deleted bots are not included by default — to get them as well, pass the include_fired=true parameter.

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

Response body

{
  "bots": [
    {
      "id": 1234567,
      "name": "Support bot",
      "is_enabled": true,
      "hook_url": "https://example.com/pyrus-hook",
      "description": "Replies to customer requests",
      "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": "en-US",
      "avatar_id": 98765
    }
  ]
}

curl

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

Parameters

include_fired	Whether to include deleted bots in the list: `true` — include, `false` — do not include. The default value is `false`.

Response fields

The bot object has the same format in all methods of this section. Empty fields are not returned.

id	Bot ID.
code	Bot code. Returned only if set.
name	Bot name.
is_enabled	Whether the bot is enabled. A disabled bot does not receive events until it is enabled again.
hook_url	URL of the bot's event handler. Pyrus sends a POST request to this URL when a task is routed to the bot.
description	Bot description.
bot_settings	Bot settings — an arbitrary string, such as message text or a JSON object. Pyrus passes it to the handler with every event, so the same handler can behave differently depending on the settings.
version	Version of the protocol Pyrus uses to communicate with the bot's handler.
login	Bot login. Used for bot authorization in the API.
external_id	External bot ID, for example, its ID in your system.
send_only_last_comment	Whether to pass only the last task comment to the handler: `true` — only the last comment, `false` — all comments.
time_zone_offset	Bot time zone — offset from UTC in minutes. Returned only if set.
locale	Bot locale, for example, `en-US`. Some date formats depend on it.
avatar_id	Bot avatar ID. Returned only if set.
external_avatar_id	External bot avatar ID. Returned only if set.
fired	Whether the bot is deleted. Returned only for deleted bots, with the value `true`.

POST /bots

This method creates a bot in the user's organization and returns it.

A new bot is enabled right away. The bot's locale matches the locale of the user who created it. The description, settings, time zone, locale, and other parameters can be set after creation with the PUT /bots/{id} method.

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

Request body

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

Response body

{
  "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": "en-US"
}

curl

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"
  }'

Parameters

name	Required. Bot name. It must not start or end with a space or contain special characters or links.
hook_url	URL of the bot's event handler. The URL must start with `https://`, and the handler must respond to POST requests. If the URL fails validation, the bot is still created, but without `hook_url`: you can set the URL later with the PUT /bots/{id} method.
external_id	External bot ID, for example, its ID in your system.

PUT /bots/{id}

This method updates the bot settings and returns the updated bot. Pass only the parameters you want to change in the request — the rest remain unchanged.

A bot can be updated by users with Configuration Manager rights and by the administrators of this bot.

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

Request body

{
  "name": "Support bot v2",
  "hook_url": "https://example.com/pyrus-hook-v2",
  "is_enabled": true,
  "bot_settings": "{\"mode\":\"prod\"}",
  "description": "Replies to customer requests",
  "send_only_last_comment": true,
  "time_zone_offset": 180,
  "locale": "en"
}

Response body

{
  "id": 1234567,
  "name": "Support bot v2",
  "is_enabled": true,
  "hook_url": "https://example.com/pyrus-hook-v2",
  "description": "Replies to customer requests",
  "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": "en-US"
}

curl

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": "Temporarily disabled"
  }'

Parameters

id	Required. Bot ID, passed in the URL.
name	New bot name. The same restrictions apply as when creating a bot.
hook_url	New URL of the bot's event handler. Must start with `https://`.
is_enabled	`true` — enable the bot, `false` — disable it.
bot_settings	Bot settings — a string that Pyrus passes to the handler with every event.
description	Bot description.
send_only_last_comment	Whether to pass only the last task comment to the handler. This helps reduce the amount of transferred data when tasks have many comments.
time_zone_offset	Bot time zone — offset from UTC in minutes, from `-720` to `840`. For example, `180` corresponds to UTC+3.
locale	Bot locale: a short (`ru`, `en`) or full (`ru-RU`, `en-US`) language code.

DELETE /bots/{id}

This method deletes the bot from the organization and returns it with the "fired": true field. The bot's tasks are transferred to the employee specified in the request.

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

Request body

{
  "task_receiver_id": 7654321
}

Response body

{
  "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": "en-US",
  "fired": true
}

curl

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
  }'

Parameters

id	Required. Bot ID, passed in the URL.
task_receiver_id	Required. ID of the employee who will receive the bot's tasks. You cannot specify a role or a deleted employee.

Bots

Methods

GET /bots

Response body

curl

Parameters

Response fields

POST /bots

Request body

Response body

curl

Parameters

PUT /bots/{id}

Request body

Response body

curl

Parameters

DELETE /bots/{id}

Request body

Response body

curl

Parameters

Was this article helpful?