bizproc.robot.add
Зарегистрировать нового робота
Описание
Метод bizproc.robot.add регистрирует нового робота.
Работает только в контексте приложения.
Параметры
CODE
string
обязательный
Внутренний идентификатор робота. Является уникальным в рамках приложения.
Допустимые символы — a-z, A-Z, 0-9, точка, дефис и нижнее подчеркивание _
HANDLER
string
обязательный
URL, на который робот будет отправлять данные через сервер очередей bitrix24.
В ссылке должен быть тот же домен, на котором установлено приложение
AUTH_USER_ID
integer
необязательный
Идентификатор пользователя, токен которого будет передан приложению
USE_SUBSCRIPTION
boolean
необязательный
Должен ли робот ожидать ответа от приложения. Возможные значения:
- Y — да
- N — нет
По умолчанию параметр пустой, что равнозначно ожиданию ответа приложения. Робот не ожидает ответа только при явном значении N
NAME
string
обязательный
Название робота.
Может быть строкой или ассоциативным массивом локализированных строк вида:
'NAME': {
'ru': 'название робота',
'en': 'robot name',
...
},DESCRIPTION
string
необязательный
Описание робота.
Может быть строкой или ассоциативным массивом локализированных строк вида:
'DESCRIPTION': {
'ru': 'описание робота',
'en': 'robot description',
...
},PROPERTIES
object
необязательный
Объект с параметрами робота. Содержит объекты, каждый из которых описывает параметр робота.
Системное название параметра должно начинаться с буквы и может содержать символы a-z, A-Z, 0-9 и нижнее подчеркивание _
RETURN_PROPERTIES
object
необязательный
Объект с дополнительными результатами робота. Содержит объекты, каждый из которых описывает параметр робота.
Параметр управляет возможностью робота ожидать ответа приложения и работать с данными, которые придут в ответе.
Системное название параметра должно начинаться с буквы и может содержать символы a-z, A-Z, 0-9 и нижнее подчеркивание _
DOCUMENT_TYPE
array
необязательный
Тип документа, который будет определять типы данных для параметров PROPERTIES и RETURN_PROPERTIES. Состоит из трех элементов типа строка:
- идентификатор модуля
- идентификатор объекта
- тип документа
Возможные варианты значений:
- Модуль CRM
['crm', 'CCrmDocumentLead', 'LEAD']— лиды
['crm', 'CCrmDocumentDeal', 'DEAL']— сделки
['crm', 'Bitrix\Crm\Integration\BizProc\Document\Quote', 'QUOTE']— коммерческие предложения
['crm', 'Bitrix\Crm\Integration\BizProc\Document\SmartInvoice', 'SMART_INVOICE']— счета
['crm', 'Bitrix\Crm\Integration\BizProc\Document\Dynamic', 'DYNAMIC_XXX']— смарт-процессы, где XXX — идентификатор смарт-процесса
FILTER
object
необязательный
Объект с правилами ограничения робота по типу документа и редакции.
Может содержать ключи:
- INCLUDE — массив правил, где робот будет отображен
- EXCLUDE — массив правил, где робот будет скрыт
Каждое правило в массиве может быть строкой или массивом типа документа в полном или частичном варианте.
Чтобы ограничить роботов по редакции Битрикс24 укажите:
- b24 — для облака
- box — для коробки
Примеры:
1. Исключить робота для коробочного Битрикс24
'FILTER': {
EXCLUDE: [ 'box' ]
}
- Отображать робота только для сделок и лидов CRM
'FILTER': {
INCLUDE: [
['crm', 'CCrmDocumentDeal'],
['crm', 'CCrmDocumentLead']
]
}USE_PLACEMENT
boolean
необязательный
Дает возможность открывать дополнительные настройки робота в слайдере приложения. Возможные значения:
- Y — да
- N — нет
PLACEMENT_HANDLER
string
необязательный
URL обработчика встройки на стороне приложения. Обязательное, если USE_PLACEMENT = 'Y'
Объект PROPERTY
Name
string
необязательный
Наименование параметра
Description
string
необязательный
Описание параметра
Type
string
необязательный
Тип параметра. Базовые значения:
- bool — да или нет
- date — дата
- datetime — дата и время
- double — число
- file — файл
- int — целое число
- select — список
- string — строка
- text — текст
- user — пользователь
Options
array
необязательный
Массив значений параметра типа список 'TYPE': select' вида:
[
'value1': 'title1',
'value2': 'title2',
'value3': 'title3',
'value4': 'title4'
]Required
boolean
необязательный
Обязательность параметра. Возможные значения:
- Y — да
- N — нет
Multiple
boolean
необязательный
Множественность параметра. Возможные значения:
- Y — да
- N — нет
Default
any
необязательный
Значение параметра по умолчанию. Для Type = 'select' указывайте ключ из Options
Примеры запроса
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"CODE":"test_robot","HANDLER":"https://your_domain/robot.php","AUTH_USER_ID":1,"USE_SUBSCRIPTION":"Y","NAME":"Отправить сообщение","PROPERTIES":{"datetime":{"Name":"Во сколько","Type":"datetime"},"text":{"Name":"Текст","Type":"text"},"user":{"Name":"Кому","Type":"user","Default":"Автор;"}},"FILTER":{"INCLUDE":[["crm","CCrmDocumentDeal"],["crm","CCrmDocumentLead"]]},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/bizproc.robot.add
try
{
const response = await $b24.callMethod(
'bizproc.robot.add',
{
'CODE': 'test_robot',
'HANDLER': 'https://your_domain/robot.php',
'AUTH_USER_ID': 1,
'USE_SUBSCRIPTION': 'Y',
'NAME': 'Отправить сообщение',
'PROPERTIES': {
'datetime': {
'Name': 'Во сколько',
'Type': 'datetime'
},
'text': {
'Name': 'Текст',
'Type': 'text'
},
'user': {
'Name': 'Кому',
'Type': 'user',
'Default': 'Автор;'
}
},
'FILTER': {
INCLUDE: [
['crm', 'CCrmDocumentDeal'],
['crm', 'CCrmDocumentLead']
]
}
}
);
const result = response.getData().result;
alert("Успешно: " + result);
}
catch( error )
{
alert("Error: " + error);
}
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.bizproc.robot.add(
code="test_robot",
handler="https://example.com/robot.php",
name="Отправить сообщение",
auth_user_id=1,
use_subscription=True,
properties={
"datetime": {
"Name": "Во сколько",
"Type": "datetime",
},
"text": {
"Name": "Текст",
"Type": "text",
},
"user": {
"Name": "Кому",
"Type": "user",
"Default": "Автор;",
},
},
filter={
"INCLUDE": [
[
"crm",
"CCrmDocumentDeal",
],
[
"crm",
"CCrmDocumentLead",
],
],
},
).response
result = bitrix_response.result
print(result)
except BitrixAPIError as error:
print(
"Ошибка Bitrix API",
f"error: {error.error}",
f"error_description: {error.error_description}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
print(f"Непредвиденная ошибка: {error}")
try {
$result = $serviceBuilder
->getBizProcScope()
->robot()
->add(
'robot_code', // string $code
'https://example.com/handler', // string $handlerUrl
1, // int $b24AuthUserId
['en' => 'Robot Name'], // array $localizedRobotName
true, // bool $isUseSubscription
[], // array $properties
false, // bool $isUsePlacement
[] // array $returnProperties
);
if ($result->isSuccess()) {
print_r($result->getCoreResponse()->getResponseData()->getResult());
} else {
print("Failed to add robot.");
}
} catch (Throwable $e) {
print("Error: " . $e->getMessage());
}
BX24.callMethod(
'bizproc.robot.add',
{
'CODE': 'test_robot',
'HANDLER': 'https://your_domain/robot.php',
'AUTH_USER_ID': 1,
'USE_SUBSCRIPTION': 'Y',
'NAME': 'Отправить сообщение',
'PROPERTIES': {
'datetime': {
'Name': 'Во сколько',
'Type': 'datetime'
},
'text': {
'Name': 'Текст',
'Type': 'text'
},
'user': {
'Name': 'Кому',
'Type': 'user',
'Default': 'Автор;'
}
},
'FILTER': {
INCLUDE: [
['crm', 'CCrmDocumentDeal'],
['crm', 'CCrmDocumentLead']
]
}
},
function(result)
{
if(result.error())
alert("Error: " + result.error());
else
alert("Успешно: " + result.data());
}
);
require_once('crest.php');
$result = CRest::call(
'bizproc.robot.add',
[
'CODE' => 'test_robot',
'HANDLER' => 'https://your_domain/robot.php',
'AUTH_USER_ID' => 1,
'USE_SUBSCRIPTION' => 'Y',
'NAME' => 'Отправить сообщение',
'PROPERTIES' => [
'datetime' => [
'Name' => 'Во сколько',
'Type' => 'datetime'
],
'text' => [
'Name' => 'Текст',
'Type' => 'text'
],
'user' => [
'Name' => 'Кому',
'Type' => 'user',
'Default' => 'Автор;'
]
],
'FILTER' => [
'INCLUDE' => [
['crm', 'CCrmDocumentDeal'],
['crm', 'CCrmDocumentLead']
]
]
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "bizproc.robot.add", b24.Params{
"CODE": "test_robot",
"HANDLER": "https://your_domain/robot.php",
"AUTH_USER_ID": 1,
"USE_SUBSCRIPTION": "Y",
"NAME": "Отправить сообщение",
"PROPERTIES": b24.Params{
"datetime": b24.Params{
"Name": "Во сколько",
"Type": "datetime",
},
"text": b24.Params{
"Name": "Текст",
"Type": "text",
},
"user": b24.Params{
"Name": "Кому",
"Type": "user",
"Default": "Автор;",
},
},
"FILTER": b24.Params{
"INCLUDE": []any{
[]string{"crm", "CCrmDocumentDeal"},
[]string{"crm", "CCrmDocumentLead"},
},
},
})
if err != nil {
return fmt.Errorf("bizproc.robot.add: %w", err)
}
var ok bool
if err := json.Unmarshal(res.Result, &ok); err != nil {
return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println("выполнено:", ok)
Ответ
HTTP-статус: 200
{
"result": true,
"time": {
"start": 1738148752.692647,
"finish": 1738148752.749058,
"duration": 0.056411027908325195,
"processing": 0.018677949905395508,
"date_start": "2025-01-29T14:05:52+03:00",
"date_finish": "2025-01-29T14:05:52+03:00",
"operating_reset_at": 1738149352,
"operating": 0
}
}
Возвращаемые данные
result
boolean
Возвращает true, если робот добавлен успешно
time
time
Информация о времени выполнения запроса
Обработка ошибок
HTTP-статус: 400
{
"error": "ERROR_ACTIVITY_VALIDATION_FAILURE",
"error_description": "Empty activity code!"
}
| Код | Описание | Значение |
|---|---|---|
ACCESS_DENIED |
Application context required | Необходим контекст приложения |
ACCESS_DENIED |
Access denied! | Метод выполнил не администратор |
ERROR_ACTIVITY_VALIDATION_FAILURE |
Empty data! | Не указаны поля с информацией |
ERROR_ACTIVITY_VALIDATION_FAILURE |
Empty activity code! | Не указан код робота |
ERROR_ACTIVITY_VALIDATION_FAILURE |
Wrong activity code! | Некорректный код робота |
ERROR_UNSUPPORTED_PROTOCOL |
Unsupported handler protocol | Некорректный протокол хендлера http, https |
ERROR_WRONG_HANDLER_URL |
Wrong handler URL | Невалидный урл хендлера |
ERROR_ACTIVITY_VALIDATION_FAILURE |
Empty activity NAME! | Не указано название робота |
ERROR_ACTIVITY_VALIDATION_FAILURE |
Wrong properties array! | Некорректно заполнены параметры PROPERTIES или RETURN_PROPERTIES |
ERROR_ACTIVITY_VALIDATION_FAILURE |
Wrong property key <ключ>! | Некорректный идентификатор свойства |
ERROR_ACTIVITY_VALIDATION_FAILURE |
Empty property NAME <ключ>! | Не указано название свойства |
ERROR_ACTIVITY_VALIDATION_FAILURE |
Wrong activity FILTER! | Некорректный фильтр |
ERROR_ACTIVITY_VALIDATION_FAILURE |
Wrong activity DOCUMENT_TYPE! | Некорректный DOCUMENT_TYPE |
ERROR_ACTIVITY_ALREADY_INSTALLED |
Activity or Robot already installed! | Робот с таким кодом уже установлен |
ERROR_ACTIVITY_ADD_FAILURE |
Activity or Robot already added! | Робот уже был добавлен |
ERROR_ACTIVITY_ADD_FAILURE |
Activity save error! | Не удалось сохранить робота, системная ошибка |

