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

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

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` — нет По умолчанию параметр пустой, что равнозначно ожиданию ответа приложения. Робот не ожидает ответа только при явном значении `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` — число `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`

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

Ниже приведены примеры объектов PROPERTY для разных типов параметров.

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

file

'attachment': {
    'Name': {
        'ru': 'Файл',
        'en': 'File'
    },
    'Description': {
        'ru': 'Файл для отправки',
        'en': 'File to send'
    },
    'Type': 'file',
    'Required': 'N',
    'Multiple': 'Y'
}

string

'Parameters': {
    'Name': {
        'ru': 'Параметры шаблона',
        'en': 'Template\'s parameters'
    },
    'Description': {
        'ru': 'ParamID={=ParamValue}',
        'en': 'ParamID={=ParamValue}'
    },
    'Type': 'string',
    'Required': 'N',
    'Multiple': 'Y'
}

Примеры кода

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

cURL (OAuth)

Python

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

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

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

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

Код	Сообщение об ошибке	Описание
`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-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус	Код Текст ошибки	Описание
`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	Превышен лимит на интенсивность запросов
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит
`401`	`NO_AUTH_FOUND` Wrong authorization data	В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука
`401`	`INVALID_REQUEST` Https required	Методы вызываются только по протоколу HTTPS
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24
`401`	`ACCESS_DENIED` REST is available only on commercial plans	REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом
`404`	`ERROR_METHOD_NOT_FOUND` Method not found!	Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на `provided by the access token`
`401`	`expired_token` The access token provided has expired	Срок действия access-токена истек
`401`	`user_access_error` The user does not have access to the application	Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям
`403`	`PORTAL_DELETED` Portal was deleted	Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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