Chatbots 2.0: Overview of Methods

Chatbots 2.0 combine two sets of APIs:
— The imbot.v2 methods manage the bot's lifecycle, messages, commands, files, and chat management.
— The im.v2 methods allow applications or users to subscribe to messenger events and receive them in polling mode—where the application periodically requests accumulated events from the server without needing a public URL for incoming requests.

Quick navigation: Quick Start | Change Log | Authorization | Bot Types | Events | Limits | All Methods

What Tasks Does This Section SolveWhat Tasks Does This Section Solve

• Register and configure a chatbot
• Receive events from the bot platform or messenger
• Send and modify messages
• Manage group chats and participants
• Upload and download files
• Register slash commands and respond to them

How to Get StartedHow to Get Started

A typical workflow with the new API:

1. Register the bot via imbot.v2.Bot.register.
2. Set up event reception via imbot.v2.Event.get or im.v2.Event.subscribe.
3. Send a message using imbot.v2.Chat.Message.send.
4. Read the original message by replyId through imbot.v2.Chat.Message.get—only for supervisor and personal type bots.
5. Get the dialogue context via imbot.v2.Chat.Message.getContext—only for supervisor and personal type bots.
6. Upload files via imbot.v2.File.upload and download them via imbot.v2.File.download.

For a detailed step-by-step scenario with cURL examples: Quick Start.

AuthorizationAuthorization

Chatbots 2.0 support two authorization methods.

WebhookWebhook

The URL contains the authorization token. This option is suitable for local integrations, AI agents, and testing.

POST https://{account}/rest/{user_id}/{webhook_token}/{method_name}
        Content-Type: application/json
        

In webhook authorization, the botToken parameter is required for imbot.v2 methods. This is a random string that you set when registering the bot and then use in all calls on behalf of that bot.

OAuthOAuth

The token is passed as the auth parameter. This option is suitable for applications from the Marketplace and internal applications.

POST https://{account}/rest/{method_name}?auth={access_token}
        Content-Type: application/json
        

In OAuth authorization, the botToken parameter for imbot.v2 is not needed because the bot is tied to the application via client_id.

Bot TypesBot Types

The fields.type parameter when registering the bot determines its behavior in chats.

The default type bot is suitable for most scenarios.

The personal type is recommended for AI assistants that require full context of group dialogue. Bots of this type will be hidden from search for users who do not have access to them in the future.

Response FormatResponse Format

All methods return a JSON response in a unified wrapper:

{
            "result": {},
            "time": {
                "start": 1700000000,
                "finish": 1700000000.5,
                "duration": 0.5,
                "date_start": "2025-01-15T10:00:00+01:00",
                "date_finish": "2025-01-15T10:00:00+01:00"
            }
        }
        

• result — data returned by the method
• time — metadata about execution time

In case of an error, instead of result, it returns:

{
            "error": "ERROR_CODE",
            "error_description": "Human-readable description"
        }
        

The error field is stable and suitable for programmatic processing (switch/case). The error_description field is intended for logging—its text may change.

Example Error HandlingExample Error Handling

$result = CRest::call('imbot.v2.Chat.Message.send', [
            'botId'    => $botId,
            'botToken' => $botToken,
            'dialogId' => $dialogId,
            'fields'   => ['message' => 'Hello'],
        ]);
        
        if (isset($result['error'])) {
            switch ($result['error']) {
                case 'BOT_NOT_FOUND':
                    // Bot deleted — re-register
                    break;
                case 'ACCESS_DENIED':
                    // Bot not in chat — skip
                    break;
                default:
                    error_log('API error: ' . $result['error'] . ' — ' . ($result['error_description'] ?? ''));
            }
        }
        

Error codes for each method are listed in the section "Possible Error Codes" on the method's page.

Boolean ParametersBoolean Parameters

Boolean parameters accept true / false. If your client does not support sending JSON booleans, you can pass the strings "Y" / "N"—the API accepts both options.

Format of dialogIdFormat of dialogId

The dialogId parameter is a universal identifier for the dialogue. It is used in methods for working with chats, messages, and files.

In personal chats, dialogId always contains the ID of the counterparty. If user 1 writes to bot 5—the bot in the event will receive dialogId = "1", and the user will receive dialogId = "5". Use the dialogId from the event for responses—it already points to the correct dialogue.

dialogId is used in methods for working with chats, messages, and files such as Chat.Message.send, Chat.get, File.upload, etc. Other methods use their own identifiers: botId (Bot.update, Event.get), commandId (Command.update), fileId (File.download). The methods im.v2.Event.* do not use dialogId.

Event Delivery ModesEvent Delivery Modes

When registering the bot, the eventMode is selected.

Polling Cycle (fetch mode)Polling Cycle (fetch mode)

A typical polling cycle for a bot with eventMode: "fetch":

$offset = 0;        // first call without offset — get all accumulated events
        $pollInterval = 10; // interval in seconds when there are no new events
        
        while (true) {
            $result = CRest::call('imbot.v2.Event.get', [
                'botId'    => $botId,
                'botToken' => $botToken,
                'offset'   => $offset,
                'limit'    => 100,
            ]);
        
            if (!empty($result['error'])) {
                // exponential backoff on errors and HTTP 429
                error_log('Event.get error: ' . $result['error']);
                sleep(min($pollInterval * 2, 60));
                continue;
            }
        
            foreach ($result['result']['events'] ?? [] as $event) {
                processEvent($event['type'], $event['data']);
            }
        
            // Confirm processed events — the next call will return only new ones
            if (!empty($result['result']['nextOffset'])) {
                $offset = $result['result']['nextOffset'];
            }
        
            // If there are more events — poll immediately, otherwise wait
            sleep(!empty($result['result']['hasMore']) ? 2 : $pollInterval);
        }
        

Recommended interval: 5–30 seconds when there are no new events. If hasMore = true — the next request should have a minimum pause of 2 seconds.

Webhook Handler (webhook mode)Webhook Handler (webhook mode)

Example handler for receiving events in eventMode: "webhook". The handler URL is passed in the fields.webhookUrl parameter when registering the bot.

// webhook_handler.php
        $data = json_decode(file_get_contents('php://input'), true);
        
        if (empty($data['event'])) {
            http_response_code(400);
            exit;
        }
        
        $eventType = $data['event'];
        $eventData = $data['data'] ?? [];
        
        // In webhook mode, all scalar values come as strings—cast types explicitly
        switch ($eventType) {
            case 'ONIMBOTV2MESSAGEADD':
                $botId    = (int)($eventData['bot']['id'] ?? 0);
                $text     = $eventData['message']['text'] ?? '';
                $dialogId = $eventData['chat']['dialogId'] ?? '';
                CRest::call('imbot.v2.Chat.Message.send', [
                    'botId'    => $botId,
                    'dialogId' => $dialogId,
                    'fields'   => ['message' => 'Received: ' . $text],
                ]);
                break;
        
            case 'ONIMBOTV2COMMANDADD':
                $botId     = (int)($eventData['bot']['id'] ?? 0);
                $commandId = (int)($eventData['command']['id'] ?? 0);
                $messageId = (int)($eventData['message']['id'] ?? 0);
                CRest::call('imbot.v2.Command.answer', [
                    'botId'     => $botId,
                    'commandId' => $commandId,
                    'messageId' => $messageId,
                    'dialogId'  => $eventData['chat']['dialogId'] ?? '',
                    'fields'    => ['message' => 'Command executed'],
                ]);
                break;
        
            case 'ONIMBOTV2JOINCHAT':
                // Bot added to chat — send a greeting
                break;
        
            case 'ONIMBOTV2DELETE':
                // Bot removed — clean up resources
                break;
        }
        
        http_response_code(200);
        echo json_encode(['status' => 'ok']);
        

The platform expects an HTTP 200 response from the handler. In case of delivery failure, retries are not guaranteed—use fetch mode for reliability.

Additional Messaging FeaturesAdditional Messaging Features

When sending messages via imbot.v2.Chat.Message.send, the following are available:

• Text Formatting (BB Codes) — bold, italic, links, quotes, code, and other BB codes
• Attachments (Attach) — structured blocks: images, tables, grids, and other elements
• Keyboards (Keyboard) — interactive buttons below the message

LimitsLimits

General limits of the Bitrix24 REST API also apply to the bot platform methods. More details: REST API Limits.

API Revisions and CompatibilityAPI Revisions and Compatibility

Bitrix24 cloud and on-premise versions may have different API revisions. To find out which revision is installed on a specific account, use imbot.v2.Revision.get.

New features, fixes, and breaking changes that affect integration compatibility are collected on the Change Log for API imbot.v2.

Overview of MethodsOverview of Methods

Chatbots Chatbots imbot.v2

Scope: imbot

Who can execute methods: owner of the registered bot

Bots

Chats

Messages

Commands

Interface

Events

A separate reference for event formats: imbot.v2/events/events.md.

Files

API Revisions

Working with Chat Working with Chat im.v2

Scope: im

Who can execute methods: user or application with access to the messenger

Events

Files

Continue Your LearningContinue Your Learning

• Change Log for API imbot.v2
• Chatbots 2.0: Quick Start
• Objects and Fields of Chatbots 2.0
• Migration from imbot to imbot.v2
• Event Formats for imbot.v2
• Working with Chat: Overview of Methods