Attachments in Messages ATTACH

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.

Attachments ATTACH allow you to add structured content to messages: text blocks, links, images, files, dividers, and tables.

Attachments

Methods that support working with ATTACH:

Chatbots 2.0 (imbot.v2)

imbot.v2.Chat.Message.send — send a message on behalf of the chatbot
imbot.v2.Chat.Message.update — modify a chatbot message
imbot.v2.Command.answer — send a chatbot response to a command

Chats (im)

im.message.add — send a message in a chat
im.message.update — modify a sent message

Notifications (im.notify)

im.notify — send a notification
im.notify.personal.add — send a personal notification
im.notify.system.add — send a system notification

Deprecated Chatbots (imbot)

imbot.message.add — send a message on behalf of the chatbot
imbot.message.update — modify a sent chatbot message
imbot.command.answer — send a chatbot response to a command

ATTACH Object Formats

You can pass ATTACH in one of two formats:

Full form: an object with attachment metadata and an array of BLOCKS
Short form: an array of blocks without a wrapper

Full Form ATTACH

PHP

ATTACH: {
            ID: 1,
            COLOR_TOKEN: 'secondary',
            COLOR: '#29619b',
            BLOCKS: [
                {...},
                {...}
            ]
        }

'ATTACH' => [
            'ID' => 1,
            'COLOR_TOKEN' => 'secondary',
            'COLOR' => '#29619b',
            'BLOCKS' => [
                [...],
                [...],
            ]
        ]

Full Form Fields

Field `type`	Description
ID `integer`	Identifier of the attachment within the message
COLOR_TOKEN `string`	Color scheme of the attachment. Allowed values: `primary`, `secondary`, `alert`, `base`. Default: `base`
COLOR `string`	Explicit HEX color of the attachment. Used for compatibility with older scripts and in some types of notifications
BLOCKS `array`	Array of content blocks in the attachment. Block types are described in the Block Collections section

Example of Full Form

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"botId":456,"botToken":"my_bot_token","dialogId":"chat20921","fields":{"message":"Attachment with primary color","attach":{"ID":1,"COLOR_TOKEN":"primary","COLOR":"#29619b","BLOCKS":[{"MESSAGE":"The API will be available in the update [B]im 24.0.0[/B]"}]}}}' \
          https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imbot.v2.Chat.Message.send

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"botId":456,"dialogId":"chat20921","fields":{"message":"Attachment with primary color","attach":{"ID":1,"COLOR_TOKEN":"primary","COLOR":"#29619b","BLOCKS":[{"MESSAGE":"The API will be available in the update [B]im 24.0.0[/B]"}]}},"auth":"**put_access_token_here**"}' \
          https://**put_your_bitrix24_address**/rest/imbot.v2.Chat.Message.send

try {
          const response = await $b24.callMethod('imbot.v2.Chat.Message.send', {
            botId: 456,
            dialogId: 'chat20921',
            fields: {
              message: 'Attachment with primary color',
              attach: {
                ID: 1,
                COLOR_TOKEN: 'primary',
                COLOR: '#29619b',
                BLOCKS: [
                  {
                    MESSAGE: 'The API will be available in the update [B]im 24.0.0[/B]'
                  }
                ]
              }
            }
          });
        
          const result = response.getData().result.id;
          console.log('Created message ID:', result);
        } catch (error) {
          console.error(error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'imbot.v2.Chat.Message.send',
                    [
                        'botId' => 456,
                        'dialogId' => 'chat20921',
                        'fields' => [
                            'message' => 'Attachment with primary color',
                            'attach' => [
                                'ID' => 1,
                                'COLOR_TOKEN' => 'primary',
                                'COLOR' => '#29619b',
                                'BLOCKS' => [
                                    [
                                        'MESSAGE' => 'The API will be available in the update [B]im 24.0.0[/B]'
                                    }
                                ]
                            ]
                        ]
                    ]
                );
        
            $result = $response->getResponseData()->getResult()['id'];
            echo 'Created message ID: ' . $result;
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error: ' . $e->getMessage();
        }

BX24.callMethod(
            'imbot.v2.Chat.Message.send',
            {
                botId: 456,
                dialogId: 'chat20921',
                fields: {
                    message: 'Attachment with primary color',
                    attach: {
                        ID: 1,
                        COLOR_TOKEN: 'primary',
                        COLOR: '#29619b',
                        BLOCKS: [
                            {
                                MESSAGE: 'The API will be available in the update [B]im 24.0.0[/B]'
                            }
                        ]
                    }
                }
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error().ex);
                } else {
                    console.log('Message ID:', result.data().id);
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'imbot.v2.Chat.Message.send',
            [
                'botId' => 456,
                'dialogId' => 'chat20921',
                'fields' => [
                    'message' => 'Attachment with primary color',
                    'attach' => [
                        'ID' => 1,
                        'COLOR_TOKEN' => 'primary',
                        'COLOR' => '#29619b',
                        'BLOCKS' => [
                            [
                                'MESSAGE' => 'The API will be available in the update [B]im 24.0.0[/B]'
                            }
                        ]
                    ]
                ]
            ]
        );
        
        if (!empty($result['error'])) {
            echo 'Error: ' . $result['error_description'];
        } else {
            echo 'Message ID: ' . $result['result']['id'];
        }

Short Form ATTACH

If attachment metadata (ID, COLOR_TOKEN, COLOR) is not needed, you can directly pass an array of blocks:

PHP

ATTACH: [
            {...},
            {...}
        ]

'ATTACH' => [
            [...],
            [...],
        ]

Example of Short Form

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"botId":456,"botToken":"my_bot_token","dialogId":"chat20921","fields":{"message":"Text block","attach":[{"MESSAGE":"The API will be available in the update [B]im 24.0.0[/B]"}]}}' \
          https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imbot.v2.Chat.Message.send

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"botId":456,"dialogId":"chat20921","fields":{"message":"Text block","attach":[{"MESSAGE":"The API will be available in the update [B]im 24.0.0[/B]"}]},"auth":"**put_access_token_here**"}' \
          https://**put_your_bitrix24_address**/rest/imbot.v2.Chat.Message.send

try {
          const response = await $b24.callMethod('imbot.v2.Chat.Message.send', {
            botId: 456,
            dialogId: 'chat20921',
            fields: {
              message: 'Text block',
              attach: [
                {
                  MESSAGE: 'The API will be available in the update [B]im 24.0.0[/B]'
                }
              ]
            }
          });
        
          const result = response.getData().result.id;
          console.log('Created message ID:', result);
        } catch (error) {
          console.error(error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'imbot.v2.Chat.Message.send',
                    [
                        'botId' => 456,
                        'dialogId' => 'chat20921',
                        'fields' => [
                            'message' => 'Text block',
                            'attach' => [
                                [
                                    'MESSAGE' => 'The API will be available in the update [B]im 24.0.0[/B]'
                                ]
                            ]
                        ]
                    ]
                );
        
            $result = $response->getResponseData()->getResult()['id'];
            echo 'Created message ID: ' . $result;
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error: ' . $e->getMessage();
        }

BX24.callMethod(
            'imbot.v2.Chat.Message.send',
            {
                botId: 456,
                dialogId: 'chat20921',
                fields: {
                    message: 'Text block',
                    attach: [
                        {
                            MESSAGE: 'The API will be available in the update [B]im 24.0.0[/B]'
                        }
                    ]
                }
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error().ex);
                } else {
                    console.log('Message ID:', result.data().id);
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'imbot.v2.Chat.Message.send',
            [
                'botId' => 456,
                'dialogId' => 'chat20921',
                'fields' => [
                    'message' => 'Text block',
                    'attach' => [
                        [
                            'MESSAGE' => 'The API will be available in the update [B]im 24.0.0[/B]'
                        }
                    ]
                ]
            ]
        );
        
        if (!empty($result['error'])) {
            echo 'Error: ' . $result['error_description'];
        } else {
            echo 'Message ID: ' . $result['result']['id'];
        }

Limitations and Errors

Maximum size of serialized ATTACH: 60000 characters
An incorrect structure returns the error ATTACH_ERROR
Exceeding the limit returns the error ATTACH_OVERSIZE

Link Validation

Supported in attachment blocks:

absolute URLs: http:// and https://
relative URLs from the root of Bitrix: /company/personal/user/1/

Warning

The content of ATTACH is not automatically transmitted in XMPP, email, and push notifications.

Continue Learning

Keyboards

About Block Collections

Attachments in Messages ATTACH

ATTACH Object FormatsATTACH Object Formats

Full Form ATTACHFull Form ATTACH

Full Form FieldsFull Form Fields

Example of Full FormExample of Full Form

Short Form ATTACHShort Form ATTACH

Example of Short FormExample of Short Form

Limitations and ErrorsLimitations and Errors

Link ValidationLink Validation

Continue LearningContinue Learning