Зарегистрировать нового робота bizproc.robot.add

Scope: bizproc

Кто может выполнять метод: администратор

Метод bizproc.robot.add регистрирует нового робота.

Работает только в контексте приложения.

Параметры метода

Обязательные параметры отмечены *

Название `тип`	Описание
CODE* `string`	Внутренний идентификатор робота. Является уникальным в рамках приложения. Допустимые символы — `a-z`, `A-Z`, `0-9`, точка, дефис и нижнее подчеркивание `_`
HANDLER* `string`	URL, на который робот будет отправлять данные через сервер очередей bitrix24. В ссылке должен быть тот же домен, на котором установлено приложение
AUTH_USER_ID `integer`	Идентификатор пользователя, токен которого будет передан приложению
USE_SUBSCRIPTION `boolean`	Должен ли робот ожидать ответа от приложения. Возможные значения: `Y` — да `N` — нет
NAME* `string` \| `object`	Название робота. Может быть строкой или ассоциативным массивом локализированных строк вида: `'NAME': { 'ru': 'название робота', 'en': 'robot name', ... },`
DESCRIPTION `string` \| `object`	Описание робота. Может быть строкой или ассоциативным массивом локализированных строк вида: `'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` — для коробки Примеры: Исключить робота для коробочного Битрикс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` \| `object`	Наименование параметра
Description `string` \| `object`	Описание параметра
Type `string`	Тип параметра. Базовые значения: `bool` — да или нет `date` — дата `datetime` — дата и время `double` — число `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`

Примеры объектов

// пример для типа select
        'docType': {
            'Name': {
                'ru': 'Тип документа',
                'en': 'Document type'
            },
            'Required': 'Y',
            'Multiple': 'N',
            'Default': 'pdf',
            'Type': 'select',
            'Options': {
                'pdf': 'PDF',
                'docx': 'DOCX'
            }
        }
        
        // пример для типа bool
        'saveDoc': {
            'Name': {
                'ru': 'Сохранить документ',
                'en': 'Save document'
            },
            'Description': {
                'ru': 'Присвоить порядковый номер',
                'en': 'Assign a sequential number'
            },
            'Type': 'bool',
            'Required': 'Y',
            'Multiple': 'N',
            'Default': 'Y'
        }
        
        // пример для типа string
        'Parameters': {
            'Name': {
                'ru': 'Параметры шаблона',
                'en': 'Template\'s parameters'
            },
            'Description': {
                'ru': 'ParamID={=ParamValue}',
                'en': 'ParamID={=ParamValue}'
            },
            'Type': 'string',
            'Required': 'N',
            'Multiple': 'Y'
        }

Примеры кода

Как использовать примеры в документации

cURL (OAuth)

PHP

BX24.js

PHP CRest

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);
        }

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

Обработка ответа

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

Название `тип`	Описание
error `string`	Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания
error_description `error_description`	Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

Возможные коды ошибок

Код	Сообщение об ошибке	Описание
`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!	Не удалось сохранить робота, системная ошибка

Статусы и коды системных ошибок

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус	Код Текст ошибки	Описание
`500`	`INTERNAL_SERVER_ERROR` Internal server error	Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	Превышен лимит на интенсивность запросов
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	Текущий метод не разрешен для вызова с помощью batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	Превышена максимальная длина параметров, переданных в метод batch
`401`	`NO_AUTH_FOUND` Wrong authorization data	Неверный access-токен или код вебхука
`400`	`INVALID_REQUEST` Https required	Для вызовов методов требуется использовать протокол HTTPS
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	REST API доступен только на коммерческих планах
`403`	`INVALID_CREDENTIALS` Invalid request credentials	У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	Манифест недоступен
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	Запрос требует более высоких привилегий, чем предоставляет токен вебхука
`401`	`expired_token` The access token provided has expired	Предоставленный access-токен доступа истек
`403`	`user_access_error` The user does not have access to the application	Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям
`500`	`PORTAL_DELETED` Portal was deleted	Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение

Обзор методов

Обновить поля робота

Зарегистрировать нового робота bizproc.robot.add

Параметры методаПараметры метода

Объект PROPERTYОбъект PROPERTY

Примеры объектовПримеры объектов

Примеры кодаПримеры кода

Обработка ответаОбработка ответа

Возвращаемые данныеВозвращаемые данные

Обработка ошибокОбработка ошибок

Возможные коды ошибокВозможные коды ошибок

Статусы и коды системных ошибокСтатусы и коды системных ошибок

Продолжите изучениеПродолжите изучение