Update the imbot.v2.Bot.update

{% note tip "" %}

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

{% endnote %}

Scope: imbot

Who can execute the method: owner of the registered bot

The method imbot.v2.Bot.update updates the properties of the bot.

Method Parameters

{% include Note on required parameters %}

#| || Name Type | Description || || botId* integer | Bot ID || || botToken string | Unique authorization token for the bot. Required for webhook authorization, not needed for OAuth.

Pass the same botToken that was specified during the chat bot registration || || fields* object | Fields to be updated. The structure of the object is described below || |#

Parameter fields {#fields}

#| || Name Type | Description || || properties object | Properties of the bot's profile. Parameter descriptions are below || || isHidden boolean | Hidden bot. Acceptable values: true, false || || isReactionsEnabled boolean | Support for reactions. Acceptable values: true, false || || isSupportOpenline boolean | Support for Open Channels. Acceptable values: true, false || || backgroundId string | Background of the bot's chat. Pass null to reset to the user's background. Available values are in the backgrounds table. An invalid value is normalized to null || || eventMode string | Event delivery mode: fetch or webhook || || webhookUrl string | URL of the event handler (applies when eventMode = webhook) || || botToken string | New botToken for token rotation. Request authorization is performed with the old token passed at the top level in the botToken parameter. An empty string or a string of spaces is ignored. Maximum length is 40 characters.

More details in the section BotToken Rotation || |#

Parameter properties {#properties}

#| || Name Type | Description || || name string | Bot's name || || lastName string | Bot's last name || || workPosition string | Bot's position (displayed in the profile) || || color string | Avatar color, available colors. If specified incorrectly, it is ignored || || gender string | Gender. Acceptable values: M, F || || avatar file | Avatar. Pass a Base64 string without the prefix data:*/*;base64,.

How to prepare data: How to upload files || |#

BotToken Rotation {#token-rotation}

Passing fields.botToken replaces the current bot token with a new one. Request authorization is performed with the old token at the top level; the new token is passed in fields.botToken.

After a successful rotation:

All the bot's subscriptions to events ONIMBOTV2* are re-linked to the new APPLICATION_TOKEN if the bot operates in webhook mode.
The old token instantly loses access to the bot — subsequent requests with it will return the error BOT_OWNERSHIP_ERROR.

In case of a collision (the new token is already linked to another bot), a generic error BOT_TOKEN_ROTATION_FAILED is returned without specifying the reason, to avoid revealing the existence of foreign tokens.

Managing Event Subscriptions {#event-subscriptions}

When calling Bot.update, the bot's subscriptions to events ONIMBOTV2* are automatically brought up to date:

#| || Change | Behavior || || webhookUrl changes (mode remains webhook) | The old eight subscriptions to the previous URL are deleted, and eight new ones are created for the new URL. The previous URL stops receiving events || || eventMode: webhook → fetch | All eight subscriptions of the bot are deleted. After the transition, events are only available through imbot.v2.Event.get || || eventMode: fetch → webhook | Eight subscriptions are created for the specified webhookUrl. If there were any "legacy" subscriptions on another URL, they are also deleted before creating new ones || || Other fields properties, isHidden, and others | Subscriptions remain unchanged || |#

{% note info "" %}

OAuth applications with multiple bots: if one application has registered multiple bots under a common clientId, the automatic cleanup of subscriptions when changing webhookUrl or eventMode is skipped to avoid affecting subscriptions of neighboring bots. Webhook-authorized bots with their own botToken do not have this limitation — each of them has its own synthetic APPLICATION_TOKEN.

{% endnote %}

Code Examples

{% include Note on examples %}

{% list tabs %}

cURL (Webhook)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"botId":456,"botToken":"my_bot_token","fields":{"properties":{"name":"Updated Bot"},"isHidden":true}}' \
  https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imbot.v2.Bot.update

cURL (OAuth)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"botId":456,"fields":{"properties":{"name":"Updated Bot"},"isHidden":true},"auth":"**put_access_token_here**"}' \
  https://**put_your_bitrix24_address**/rest/imbot.v2.Bot.update

try {
  const response = await $b24.callMethod('imbot.v2.Bot.update', {
    botId: 456,
    fields: {
      properties: { name: 'Updated Bot' },
      isHidden: true,
    },
  });

  const { result } = response.getData();
  console.log('result:', result);
} catch (error) {
  console.error('Error:', error);
}

PHP

try {
    $response = $b24Service
        ->core
        ->call(
            'imbot.v2.Bot.update',
            [
                'botId' => 456,
                'fields' => [
                    'properties' => ['name' => 'Updated Bot'],
                    'isHidden' => true,
                ],
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'result: '. print_r($result, true);
} catch (Throwable $exception) {
    error_log($exception->getMessage());
    echo 'Error: '. $exception->getMessage();
}

BX24.js

BX24.callMethod(
    'imbot.v2.Bot.update',
    {
        botId: 456,
        fields: {
            properties: { name: 'Updated Bot' },
            isHidden: true,
        },
    },
    function(result) {
        if (result.error()) {
            console.error(result.error().ex);
        } else {
            console.log(result.data());
        }
    }
);

PHP CRest

require_once('crest.php');

$result = CRest::call(
    'imbot.v2.Bot.update',
    [
        'botId' => 456,
        'fields' => [
            'properties' => ['name' => 'Updated Bot'],
            'isHidden' => true,
        ],
    ]
);

if (!empty($result['error'])) {
    echo 'Error: '. $result['error_description'];
} else {
    echo 'Success';
}

// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "imbot.v2.Bot.update", b24.Params{
	"botId":    456,
	"botToken": "my_bot_token",
	"fields": b24.Params{
		"properties": b24.Params{
			"name": "Updated Bot",
		},
		"isHidden": true,
	},
})
if err != nil {
	return fmt.Errorf("imbot.v2.Bot.update: %w", err)
}

// The response shape is shown below on this page.
fmt.Printf("%s\n", res.Result)

{% endlist %}

Response Handling

HTTP status: 200

{
    "result": {
        "bot": {
            "id": 456,
            "code": "support_bot",
            "type": "bot",
            "isHidden": true,
            "isSupportOpenline": false,
            "isReactionsEnabled": true,
            "backgroundId": null,
            "language": "de",
            "moduleId": "rest",
            "eventMode": "fetch",
            "countMessage": 150,
            "countCommand": 3,
            "countChat": 12,
            "countUser": 45
        },
        "users": [
            {
                "id": 456,
                "active": true,
                "name": "Updated Bot",
                "bot": true,
                "type": "bot"
            }
        ]
    },
    "time": {
        "start": 1728626400.123,
        "finish": 1728626400.234,
        "duration": 0.111,
        "processing": 0.045,
        "date_start": "2024-10-11T10:00:00+02:00",
        "date_finish": "2024-10-11T10:00:00+02:00"
    }
}

Returned Data

#| || Name Type | Description || || result object | Update result || || result.bot Bot | Updated bot object in extended format (detailed description) || || result.users User[] | Array of related users (detailed description) || || time time | Information about the request execution time || |#

Fields of the Bot Object {#bot-object}

#| || Field Type | Description || || id integer | Bot identifier || || code string | Symbolic code of the bot || || type string | Type of bot || || isHidden boolean | Bot is hidden from the contact list || || isSupportOpenline boolean | Bot supports open channels || || isReactionsEnabled boolean | Reactions are enabled for bot messages || || backgroundId string|null | Chat background ID or null || || language string | Bot's language || || moduleId string | Module identifier || || eventMode string | Event delivery mode: webhook or fetch || || countMessage integer | Number of messages sent by the bot || || countCommand integer | Number of registered commands || || countChat integer | Number of bot chats || || countUser integer | Number of users who interacted with the bot || |#

Fields of the User Object {#user-object}

#| || Field Type | Description || || id integer | User identifier || || active boolean | User is active || || name string | User's first and last name || || bot boolean | Indicates a bot user || || type string | User type || |#

A complete description of all object fields can be found on the Objects and Fields page.

Error Handling

HTTP status: 400, 403

{
    "error": "BOT_NOT_FOUND",
    "error_description": "Bot not found"
}

{% include notitle Error Handling %}

Possible Error Codes

#| || Code | Description | Value || || BOT_TOKEN_NOT_SPECIFIED | Bot token is not specified | botToken is not specified. Required for webhook authorization || || BOT_ID_REQUIRED | Bot ID is required | botId is not specified || || BOT_NOT_FOUND | Bot not found | Bot not found || || BOT_OWNERSHIP_ERROR | Bot is registered by another application | Bot is registered by another application || || BOT_INVALID_EVENT_MODE | Invalid event mode | Invalid event delivery mode || || BOT_INVALID_CALLBACK | Invalid callback URL | Invalid event handler URL || || BOT_AVATAR_INCORRECT_TYPE | Avatar must be an image | Avatar must be an image (image/*) || || BOT_AVATAR_INCORRECT_SIZE | Avatar exceeds maximum size | Avatar size exceeds maximum (5000×5000 px) || || BOT_TOKEN_ROTATION_FAILED | Bot token rotation failed | Bot token rotation failed. Generic error code — reason is not disclosed to avoid confirming the existence of foreign tokens || |#

{% include System Errors %}

Navigation Menu

Uh oh!

Update the imbot.v2.Bot.update

Method Parameters

Parameter fields {#fields}

Parameter properties {#properties}

BotToken Rotation {#token-rotation}

Managing Event Subscriptions {#event-subscriptions}

Code Examples

Response Handling

Returned Data

Fields of the Bot Object {#bot-object}

Fields of the User Object {#user-object}

Error Handling

Possible Error Codes

Continue Learning

Uh oh!

FilesExpand file tree

bot-update.md

Latest commit

History

bot-update.md

File metadata and controls

Update the imbot.v2.Bot.update

Method Parameters

Parameter fields {#fields}

Parameter properties {#properties}

BotToken Rotation {#token-rotation}

Managing Event Subscriptions {#event-subscriptions}

Code Examples

Response Handling

Returned Data

Fields of the Bot Object {#bot-object}

Fields of the User Object {#user-object}

Error Handling

Possible Error Codes

Continue Learning