Register the Service ai.engine.register

Choose a tool for developing with an AI agent:

use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

Scope: ai_admin

Who can execute the method: administrator

The method ai.engine.register registers a custom AI service.

The method is available in Bitrix24 Cloud. It is not registered in the REST API in the on-premise edition.

Method Parameters

Required parameters are marked with *

Name `type`	Description
name* `string`	The name of the service that will be displayed in the interface
code* `string`	A unique code for the service. Only characters `A-Za-z0-9-_` are allowed
category* `string`	The category of the service. Possible values: `text` — text requests `image` — image generation `audio` — audio processing `call` — call recording processing `vision` — image analysis `classify` — data classification
completions_url* `string`	The URL endpoint of the handler, which must respond with HTTP status `200` during registration verification (detailed description)
settings `object`	Additional settings for the service (detailed description). If the parameter is not passed, an empty settings set is saved

Settings Parameter

The method accepts settings as a JSON object without a strict schema. The following fields are used in the service code:

Name `type`	Description
code_alias `string`	The alias of the model. Defaults to `ChatGPT`
model_context_type `string`	The method of calculating context. Possible values: `token` — count by tokens `symbol` — count by characters Defaults to `token`
model_context_limit `integer`	The context limit. Defaults to `15666`

Endpoint

completions_url must point to your endpoint that accepts requests from Bitrix24 and processes them in the expected format.

You can use the endpoint template as a foundation. In production, separate request acceptance from request processing.

The template endpoint can be used as a basis for your own service.

Endpoint Requirements

The endpoint must quickly accept the request and return a response or queue the task in its internal queue. The initial response time should not exceed five seconds — after the timeout, the connection is terminated.
Processing must be asynchronous: acknowledge the request and send the result through a callback.
The request payload includes callbackUrl and errorCallbackUrl. After processing, the result should be sent to callbackUrl, and error information to errorCallbackUrl.
In response to the POST request, the endpoint must return JSON and HTTP status 202. Any other status is considered a processing error.

The ttl parameter contains the planned job lifetime in seconds. The default is 14400, and the maximum is 86400. After the lifetime expires, errorCallbackUrl no longer accepts an error. A successful result may be accepted by callbackUrl later while the job record still exists, but you should not rely on this behavior.

The endpoint's response to the initial request does not replace the callback mechanism. After accepting the request successfully, the endpoint must return HTTP status 202 and json_encode(['result' => 'OK']).

Features for the Audio Category

For the audio category, the prompt key receives an object with the following fields:

Name `type`	Description
file `string`	Link to the file. The file may come without an extension
fields `object`	Additional data about the file (detailed description)
fileExtension `string`	The file extension, if it can be determined. May come as an empty string

Fields Object

Name `type`	Description
type `string`	Content-Type of the file. Especially important if the file is sent without an extension, e.g., `audio/ogg`
prompt `string`	Auxiliary prompt for file recognition, e.g., company name

Features for the Image Category

For the image category, the prompt key receives an object with the following fields:

Name `type`	Description
prompt `string`	Text description of what needs to be generated
style `string`	The style of image generation. May be absent if no style was specified
format `string` \| `null`	Image format. Possible values: `square` — square image with a 1:1 ratio, 1024×1024 pixels `portrait` — vertical image with a 9:16 ratio, 1024×1792 pixels `landscape` — horizontal image with a 16:9 ratio, 1792×1024 pixels `null` — format is not specified
images_number `integer`	The number of images to generate. May be absent if no value was specified

Additional Fields in the Request to the Endpoint

Name `type`	Description
auth `object` \| `null`	Application authorization data. Returns `null` if the service is registered without application context
payload_raw `string`	Raw value of the prompt. When using BitrixGPT, this may contain the symbolic code of the used prompt
payload_provider `string`	Symbolic code of the pre-prompt provider. When using BitrixGPT, this may contain `prompt`
payload_prompt_text `string` \| `null`	If `payload_provider = prompt`, contains the original pre-prompt instruction. For other `payload_provider` values, returns `null`
payload_markers `object`	Additional user markers used in prompt formation
payload_role `string` \| `null`	Role or instruction used in prompt formation. In GPT-like systems, this value is usually passed as a system message. Returns `null` if the role is not specified
collect_context `boolean`	A flag indicating whether to pass context to the model
context `array`	An array of previous messages in chronological order. The volume sent depends on the provider's settings and the type of context calculation
max_tokens `integer`	Maximum number of tokens in the response
temperature `double`	A parameter that controls the degree of randomness of the output
callbackUrl `string`	URL to which the result of successful processing should be sent
errorCallbackUrl `string`	URL to which error information should be sent
ttl `integer`	Planned job lifetime in seconds. The default is `14400`, and the maximum is `86400`

Context should only be passed to the model if the request includes collect_context = true. If the parameter is absent or set to false, context can be omitted.

Endpoint Request and Callback Example

Bitrix24 sends a POST request to completions_url. The set of additional fields depends on the scenario. Example for the text category:

{
            "prompt": "Prepare a brief meeting summary",
            "payload_raw": "Prepare a brief meeting summary",
            "payload_provider": "text",
            "payload_prompt_text": null,
            "payload_markers": {
                "language": "en"
            },
            "payload_role": "You are an assistant that prepares summaries",
            "context": [
                {
                    "role": "user",
                    "content": "We discussed the launch timeline and assignees"
                }
            ],
            "collect_context": true,
            "max_tokens": 1000,
            "temperature": 0.7,
            "auth": null,
            "category": "text",
            "ttl": 14400,
            "callbackUrl": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=ai.controller.integration.thirdparty.callbackSuccess&hash=example&rid=example",
            "errorCallbackUrl": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=ai.controller.integration.thirdparty.callbackError&hash=example&rid=example"
        }

After accepting the request, the endpoint must return HTTP status 202 and JSON within five seconds:

{
            "result": "OK"
        }

After processing, send the result to callbackUrl in a POST request:

{
            "result": "The launch is scheduled for September 15. The assignee is Klaus Weber."
        }

If processing fails, send the error to errorCallbackUrl:

{
            "message": "Provider temporarily unavailable",
            "code": 503,
            "api_request_completed": false
        }

The api_request_completed field indicates whether the request to the AI provider was completed. If the value is false, Bitrix24 restores the deducted limit.

Example structure of a message for a GPT-like model:

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

Code Examples

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

JS (TS)

JS (UMD)

Python

PHP

BX24.js

PHP CRest

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

// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        try {
          const response = await $b24.actions.v2.call.make<number>({
            method: 'ai.engine.register',
            params: {
              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,
              },
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Registered AI engine ID:', result)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function registerAiEngine() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'ai.engine.register',
                params: {
                  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,
                  },
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Registered AI engine ID:', result)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', registerAiEngine)
        </script>

from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.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,
                },
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected 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>';

// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "ai.engine.register", b24.Params{
        	"name":            "Acme GPT",
        	"code":            "acme_gpt",
        	"category":        "text",
        	"completions_url": "https://api.example.com/bitrix24/ai/completions",
        	"settings": b24.Params{
        		"code_alias":          "ChatGPT",
        		"model_context_type":  "token",
        		"model_context_limit": 15666,
        	},
        })
        if err != nil {
        	return fmt.Errorf("ai.engine.register: %w", err)
        }
        
        var value b24.ID
        if err := json.Unmarshal(res.Result, &value); err != nil {
        	return fmt.Errorf("parse response: %w", err)
        }
        fmt.Println("result:", value)

Response Handling

HTTP Status: 200

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

Returned Data

Name `type`	Description
result `integer`	Identifier of the registered service
time `time`	Information about the execution time of the request

Error Handling

HTTP Status: 400

{
            "error": "ENGINE_REGISTER_ERROR_CODE_UNIQUE",
            "error_description": "A record with this `code` already exists."
        }

Name `type`	Description
error `string`	String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only `error_description` shows the reason
error_description `string`	Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Code	Description	Value
`ENGINE_REGISTER_ERROR_NAME`	The `name` key with a string value is required	The `name` parameter is missing, an empty value is provided, or the value is not a string
`ENGINE_REGISTER_ERROR_CODE`	The `code` key with a string value is required	The `code` parameter is missing, an empty value is provided, or the value is not a string
`ENGINE_REGISTER_ERROR_CODE_FORMAT`	The `code` key must contain only characters `A-Za-z0-9-_`	Invalid characters are present in `code`
`ENGINE_REGISTER_ERROR_CODE_UNIQUE`	A record with this `code` already exists	A service with this code is already registered in the same category
`ENGINE_REGISTER_ERROR_CATEGORY`	The `category` key is required	The `category` parameter is missing or an empty value is provided
`ENGINE_REGISTER_ERROR_CATEGORY_FORMAT`	The `category` key can contain one of the values: `text, image, audio, call, vision, classify`	The provided `category` value is not in the list of available categories
`ENGINE_REGISTER_ERROR_COMPLETIONS_URL`	The `completions_url` key with a string value is required	The `completions_url` parameter is missing, an empty value is provided, or the value is not a string
`ENGINE_REGISTER_ERROR_COMPLETIONS_URL_FAIL`	The value of the `completions_url` key must be a valid URL that returns status `200` upon verification	The URL is unavailable, invalid, or returns a status other than `200` upon verification
`ENGINE_REGISTER_ERROR_SETTINGS_FORMAT`	The value of the `settings` key must be valid JSON	The `settings` parameter is not provided as an object

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit
`401`	`NO_AUTH_FOUND` Wrong authorization data	The request contains no authorization data: neither an access token nor a webhook code was passed
`401`	`INVALID_REQUEST` Https required	Methods are called over the HTTPS protocol only
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support
`401`	`ACCESS_DENIED` REST is available only on commercial plans	REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	No active webhook with the specified user identifier and secret code was found
`404`	`ERROR_METHOD_NOT_FOUND` Method not found!	No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with `provided by the access token`
`401`	`expired_token` The access token provided has expired	The access token has expired
`401`	`user_access_error` The user does not have access to the application	The application is installed, but the Bitrix24 administrator has granted access to it only to specific users
`403`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Was the article helpful?

Overview of Methods

Get List of Services

Register the Service ai.engine.register

Method ParametersMethod Parameters

Settings ParameterSettings Parameter

EndpointEndpoint

Endpoint RequirementsEndpoint Requirements

Features for the Audio CategoryFeatures for the Audio Category

Fields ObjectFields Object

Features for the Image CategoryFeatures for the Image Category

Additional Fields in the Request to the EndpointAdditional Fields in the Request to the Endpoint

Endpoint Request and Callback ExampleEndpoint Request and Callback Example

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning