Зарегистрировать сервис ai.engine.register

Если вы разрабатываете интеграции для Битрикс24 с помощью AI-инструментов (Codex, Claude Code, Cursor), подключите MCP-сервер, чтобы ассистент использовал официальную REST-документацию.

Scope: ai_admin

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

Метод ai.engine.register регистрирует пользовательский AI-сервис.

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

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

Название
тип

Описание

name*
string

Название сервиса, которое будет отображаться в интерфейсе

code*
string

Уникальный код сервиса.

Допустимы только символы A-Za-z0-9-_

category*
string

Категория сервиса.

Возможные значения:

  • text
  • image
  • audio
  • call

completions_url*
string

URL endpoint обработчика, который должен отвечать HTTP-статусом 200 при проверке регистрации (подробное описание)

settings
object

Дополнительные настройки сервиса (подробное описание)

Параметр settings

Метод принимает settings как JSON-объект без жесткой схемы. В коде сервиса используются следующие поля:

Название
тип

Описание

code_alias
string

Псевдоним модели.

По умолчанию используется ChatGPT

model_context_type
string

Способ подсчета контекста.

Возможные значения:

  • token
  • symbol

По умолчанию используется token

model_context_limit
integer

Лимит контекста.

По умолчанию используется 15666

Endpoint

completions_url должен указывать на ваш endpoint, который принимает запросы от Битрикс24 и обрабатывает их по ожидаемому формату.

Внимание!

Код endpoint из примеров можно использовать как основу, но для production обработку лучше выносить в отдельные части приложения.

Шаблон endpoint можно использовать как основу для собственного сервиса.

Требования к endpoint

  1. Endpoint должен быстро принять запрос и вернуть ответ или поставить задачу в свою внутреннюю очередь. На первичный ответ даётся не более 5 секунд — по истечении таймаута соединение обрывается
  2. Для категории image обработку нужно строить асинхронно
  3. В payload запроса приходят callbackUrl и errorCallbackUrl. После обработки нужно отправлять результат в callbackUrl, а информацию об ошибке в errorCallbackUrl
  4. Endpoint должен корректно возвращать HTTP-статусы:
  • 200 — запрос обработан сразу
  • 202 — запрос принят и поставлен в очередь
  • 503 — сервис временно недоступен

Ссылка callbackUrl имеет ограниченное время жизни — оно приходит в параметре ttl (в секундах). Если endpoint не успеет отправить результат до истечения этого срока, ссылка станет недействительной и пользователь не получит ответ.

Внимание!

Ответ endpoint на исходный запрос не заменяет callback-механику. При успешном принятии запроса endpoint должен возвращать json_encode(['result' => 'OK']).

Особенности для категории audio

Для категории audio в ключе prompt приходит объект со следующими полями:

Название
тип

Описание

file
string

Ссылка на файл. Файл может приходить без расширения

fields
object

Дополнительные данные о файле (подробное описание)

fileExtension
string

Расширение файла, если его удалось определить. Может приходить пустой строкой

Объект fields

Название
тип

Описание

type
string

Content-Type файла. Особенно важен, если файл передан без расширения, например audio/ogg

prompt
string

Вспомогательный промпт для распознавания файла, например название компании

Особенности для категории image

Для категории image в ключе prompt приходит объект со следующими полями:

Название
тип

Описание

prompt
string

Текстовое описание того, что нужно сгенерировать

style
string

Стиль генерации изображения. Может отсутствовать, если стиль не был задан

format
string

Формат изображения, например square, landscape. Может приходить null, если формат не был задан

images_number
integer

Количество изображений, которое нужно сгенерировать. Может отсутствовать, если значение не было задано

Дополнительные поля в запросе к endpoint

Название
тип

Описание

auth
object

Данные авторизации

payload_raw
string

Сырое значение промпта. При использовании BitrixGPT здесь может приходить символьный код использованного промпта

payload_provider
string

Символьный код провайдера препромпта. При использовании BitrixGPT здесь может приходить prompt

payload_prompt_text
string

Если payload_provider = prompt, содержит сырую инструкцию препромпта

payload_markers
object

Дополнительные маркеры пользователя, использованные при формировании промпта

payload_role
string

Роль или инструкция, использованная при формировании промпта. В GPT-подобных системах это значение обычно передают как системное сообщение

collect_context
boolean

Флаг, который показывает, нужно ли передавать контекст в модель

context
array

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

max_tokens
integer

Максимальное число лексем в ответе

temperature
number

Параметр, который управляет степенью случайности вывода

callbackUrl
string

URL, на который нужно отправить результат успешной обработки

errorCallbackUrl
string

URL, на который нужно отправить информацию об ошибке

ttl
integer

Время жизни ссылки callbackUrl в секундах. По истечении этого срока ссылка станет недействительной

Контекст нужно передавать в модель только если в запросе пришел collect_context = true. Если параметр отсутствует или равен false, контекст можно не использовать.

Пример структуры сообщения для GPT-подобной модели:

[
            {
                "role": "system",
                "content": "$payload_role"
            },
            {
                "role": "user",
                "content": "$prompt"
            }
        ]

Примеры кода

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

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{
            "name": "Acme GPT",
            "code": "acme_gpt",
            "category": "text",
            "completions_url": "https://api.example.com/bitrix24/ai/completions",
            "settings": {
              "code_alias": "ChatGPT",
              "model_context_type": "token",
              "model_context_limit": 15666
            }
          }' \
          https://**put_your_bitrix24_address**/rest/**put_your_webhook_id**/**put_your_webhook_code**/ai.engine.register.json
        
curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{
            "name": "Acme GPT",
            "code": "acme_gpt",
            "category": "text",
            "completions_url": "https://api.example.com/bitrix24/ai/completions",
            "settings": {
              "code_alias": "ChatGPT",
              "model_context_type": "token",
              "model_context_limit": 15666
            },
            "auth": "**put_access_token_here**"
          }' \
          https://**put_your_bitrix24_address**/rest/ai.engine.register
        
try
        {
            const response = await $b24.callMethod(
                'ai.engine.register',
                {
                    name: 'Acme GPT',
                    code: 'acme_gpt',
                    category: 'text',
                    completions_url: 'https://api.example.com/bitrix24/ai/completions',
                    settings: {
                        code_alias: 'ChatGPT',
                        model_context_type: 'token',
                        model_context_limit: 15666
                    }
                }
            );
        
            const result = response.getData().result;
            console.log('Engine registered:', result);
        }
        catch (error)
        {
            console.error('Error:', error);
        }
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'ai.engine.register',
                    [
                        'name' => 'Acme GPT',
                        'code' => 'acme_gpt',
                        'category' => 'text',
                        'completions_url' => 'https://api.example.com/bitrix24/ai/completions',
                        'settings' => [
                            'code_alias' => 'ChatGPT',
                            'model_context_type' => 'token',
                            'model_context_limit' => 15666,
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error registering AI engine: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'ai.engine.register',
            {
                name: 'Acme GPT',
                code: 'acme_gpt',
                category: 'text',
                completions_url: 'https://api.example.com/bitrix24/ai/completions',
                settings: {
                    code_alias: 'ChatGPT',
                    model_context_type: 'token',
                    model_context_limit: 15666
                }
            },
            function(result)
            {
                if (result.error())
                {
                    console.error(result.error(), result.error_description());
                }
                else
                {
                    console.log(result.data());
                }
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'ai.engine.register',
            [
                'name' => 'Acme GPT',
                'code' => 'acme_gpt',
                'category' => 'text',
                'completions_url' => 'https://api.example.com/bitrix24/ai/completions',
                'settings' => [
                    'code_alias' => 'ChatGPT',
                    'model_context_type' => 'token',
                    'model_context_limit' => 15666,
                ],
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

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

HTTP-статус: 200

{
            "result": 12,
            "time": {
                "start": 1774078200,
                "finish": 1774078200.315271,
                "duration": 0.31527090072631836,
                "processing": 0.02,
                "date_start": "2026-03-20T09:50:00+03:00",
                "date_finish": "2026-03-20T09:50:00+03:00",
                "operating_reset_at": 1774078800,
                "operating": 0
            }
        }

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

Название
тип

Описание

result
integer

Идентификатор зарегистрированного сервиса

time
time

Информация о времени выполнения запроса

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

HTTP-статус: 400

{
            "error": "ENGINE_REGISTER_ERROR_CODE_UNIQUE",
            "error_description": "Запись с таким `code` уже существует."
        }

Название
тип

Описание

error
string

Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания

error_description
error_description

Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

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

Код

Описание

Значение

ENGINE_REGISTER_ERROR_NAME

Ключ name со строковым значением обязателен

Не передан параметр name, передано пустое значение или значение не является строкой

ENGINE_REGISTER_ERROR_CODE

Ключ code со строковым значением обязателен

Не передан параметр code, передано пустое значение или значение не является строкой

ENGINE_REGISTER_ERROR_CODE_FORMAT

Ключ code должен содержать только символы A-Za-z0-9-_

В code переданы недопустимые символы

ENGINE_REGISTER_ERROR_CODE_UNIQUE

Запись с таким code уже существует

Сервис с таким кодом уже зарегистрирован в той же категории

ENGINE_REGISTER_ERROR_CATEGORY

Ключ category обязателен

Не передан параметр category или передано пустое значение

ENGINE_REGISTER_ERROR_CATEGORY_FORMAT

Ключ category может содержать одно из значений: text, image, audio, call

Передано значение category, которого нет в списке доступных категорий

ENGINE_REGISTER_ERROR_COMPLETIONS_URL

Ключ completions_url со строковым значением обязателен

Не передан параметр completions_url, передано пустое значение или значение не является строкой

ENGINE_REGISTER_ERROR_COMPLETIONS_URL_FAIL

Значением ключа completions_url должен быть валидный URL , который при проверке возвращает статус 200

URL недоступен, невалиден или при проверке возвращает статус, отличный от 200

ENGINE_REGISTER_ERROR_SETTINGS_FORMAT

Значением ключа settings должен быть валидный JSON

Параметр settings передан не в виде объекта

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

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

Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

Предыдущая
Обзор методов
Следующая
Получить список сервисов