Register a Chat Application imbot.app.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: imbot

Who can execute the method: any user

The method imbot.app.register registers a chat application.

Applications are divided into two types: JS command and IFRAME application.

Method Parameters for JS Command

Name

Example

Description

BOT_ID

62

Identifier of the bot that owns the chat application

CODE

'echo'

Code of the chat application

JS_METHOD

'SEND'

Options for JS_METHOD:

  • PUT — inserts a command to the chat bot in the textarea, JS_PARAM can only contain the command text and its parameters (allowed characters: a-z 0-9 - + _ / )
  • SEND — sends a command to the chat bot, JS_PARAM can only contain the command text and its parameters (allowed characters a-z 0-9 - + _ / )
  • CALL — calls a phone number
  • SUPPORT — opens the support chat bot working through Open Channels, JS_PARAM must specify the open channel code (32 characters)

JS_PARAM

'/help'

ICON_FILE

'/* base64 image */'

Icon in base64.
The format of the icon ICON_FILE:

  • This field must contain the base64 of your icon, the icon format is detailed in the documentation
  • Note that if this field is not specified, the application will be available in the system dialog "Chat Applications"

CONTEXT

'BOT'

Context of the application.
The CONTEXT indicates where the application will be available:

  • ALL — in all chats
  • USER — only in one-on-one chats
  • CHAT — only in group chats
  • BOT — only with the chat bot that installed the application
  • LINES — only in Open Channels chats
  • CALL — only in chats created within Telephony

Each context can have the postfix -admin, then the application will be available in the specified context only to Bitrix24 administrators

EXTRANET_SUPPORT

'N'

Is the command available to extranet users, default is N

LIVECHAT_SUPPORT

'N'

Online chat support

IFRAME_POPUP

'N'

The iframe will open with the ability to move within the messenger, switching between dialogs will not close such a window.

LANG

Array(...)

Array of translations, it is advisable to specify at least for DE and EN

LANGUAGE_ID (LANG)

'en'

Language identifier for translation

TITLE (LANG)

'Echobot BUTTON'

Title for the button or command in the specified language

DESCRIPTION (LANG)

'Send help command'

Description of the command in the specified language

Code Example

Note

This example uses the restCommand function. This is a method for sending data to Bitrix24. You can use your own function to call the method, the JavaScript method BX24.callMethod or industry standard B24PhpSDK.

How to Use Examples in Documentation

$result = restCommand(
            'imbot.app.register',
            Array(
                'BOT_ID' => 62,
                'CODE' => 'echo',
                'JS_METHOD' => 'SEND',
                'JS_PARAM' => '/help',
                'ICON_FILE' => '/* base64 image */',
                'CONTEXT' => 'BOT',
                'EXTRANET_SUPPORT' => 'N',
                'LIVECHAT_SUPPORT' => 'N',
                'IFRAME_POPUP' => 'N',
                'LANG' => Array(
                    Array(
                        'LANGUAGE_ID' => 'en',
                        'TITLE' => 'Echobot BUTTON',
                        'DESCRIPTION' => 'Send help command'
                    ),
                )
            ),
            $_REQUEST["auth"]
        );

Method Parameters for IFRAME Application

Name

Example

Description

BOT_ID

62

Identifier of the bot that owns the chat application

CODE

'echo'

Code of the chat application

IFRAME

'https://marta.bitrix.com/iframe/echo.php'

URL of the iframe

IFRAME_WIDTH

'350'

Desired width of the iframe. Minimum value - 250px

IFRAME_HEIGHT

'150'

Desired height of the iframe. Minimum value - 50px

HASH

'd1ab17949a572b0979d8db0d5b349cd2'

Token for accessing your iframe for signature verification, 32 characters

ICON_FILE

'/* base64 image */'

Icon in base64

CONTEXT

'BOT'

Context

HIDDEN

'N'

Is the application hidden or not

EXTRANET_SUPPORT

'N'

Is the command available to extranet users, default is N

LIVECHAT_SUPPORT

'N'

Online chat support

IFRAME_POPUP

'N'

The iframe will open with the ability to move within the messenger, switching between dialogs will not close such a window

LANG

Array(...)

Array of translations, it is advisable to specify at least for DE and EN

LANGUAGE_ID (LANG)

'en'

Language identifier for translation

TITLE (LANG)

'Echobot IFRAME'

Title for the button or command in the specified language

DESCRIPTION (LANG)

'Open Echobot IFRAME app'

Description of the command in the specified language

COPYRIGHT (LANG)

'Bitrix24'

Copyright

Please note:

  1. Although you specify the window sizes when registering the IFRAME application, it may be reduced by the application to the actually available sizes. The ideal option is to make it fit within the minimum sizes and be able to freely adapt to increase and decrease, which will be very important for mobile devices.
  2. The link to IFRAME must lead to a site with an active HTTPS certificate. You can read the rules for developing IFRAME handlers and limitations in the documentation.
  3. Always use hash checks before performing any operations.
  4. Applications are only available after reloading the page or after a service hit to the server (this varies by installation, from 15 to 26 minutes). The application will appear instantly only when interacting with the context button.
  5. In the values of IFRAME_WIDTH and IFRAME_HEIGHT, you specify the desired width and height of the application window. The application window will be reduced to the size of the messenger window if the messenger window is smaller. Conversely, if it is larger, the desired sizes for the application will be used.
  6. If the application is called from the context (keyboard or menu), it will be invoked in context mode. In this mode, the value of IFRAME_POPUP will be ignored.

Code Example

Note

This example uses the restCommand function. This is a method for sending data to Bitrix24. You can use your own function to call the method, the JavaScript method BX24.callMethod or industry standard B24PhpSDK.

How to Use Examples in Documentation

$result = restCommand(
            'imbot.app.register',
            Array(
                'BOT_ID' => 62,
                'CODE' => 'echo',
                'IFRAME' => 'https://marta.bitrix.com/iframe/echo.php',
                'IFRAME_WIDTH' => '350',
                'IFRAME_HEIGHT' => '150',
                'HASH' => 'd1ab17949a572b0979d8db0d5b349cd2',
                'ICON_FILE' => '/* base64 image */',
                'CONTEXT' => 'BOT',
                'HIDDEN' => 'N',
                'EXTRANET_SUPPORT' => 'N',
                'LIVECHAT_SUPPORT' => 'N',
                'IFRAME_POPUP' => 'N',
                'LANG' => Array(
                    Array(
                        'LANGUAGE_ID' => 'en',
                        'TITLE' => 'Echobot IFRAME',
                        'DESCRIPTION' => 'Open Echobot IFRAME app',
                        'COPYRIGHT' => 'Bitrix24'
                    ),
                )
            ),
            $_REQUEST["auth"]
        );

Returned Data

Numeric identifier of the created application APP_ID.

Possible Error Codes

Code

Description

BOT_ID_ERROR

Chat bot not found

APP_ID_ERROR

The chat application does not belong to this rest application. You can only work with chat applications installed within the current rest application

IFRAME_HTTPS

The link to IFRAME must lead to a site with an active HTTPS certificate

HASH_ERROR

You did not specify a hash for the application. We recommend using unique hashes for each IFRAME and each installation

PARAMS_ERROR

Error specifying JS command or IFRAME parameters

LANG_ERROR

Language phrases for the visible command were not provided

WRONG_REQUEST

Something went wrong

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

Previous
About Creating an Application
Next
Update Application Information in Chat