Attachments in Messages ATTACH

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:

im.message.add — send a message in a chat
im.message.update — modify a sent message
im.notify — send a notification
im.notify.personal.add — send a personal notification
im.notify.system.add — send a system notification
imbot.message.add — send a message on behalf of a chat bot
imbot.message.update — modify a chat bot's message
imbot.command.answer — send a chat bot's 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

ATTACH Object

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 '{"DIALOG_ID":"chat20921","MESSAGE":"Attachment with primary color","ATTACH":{"ID":1,"COLOR_TOKEN":"primary","COLOR":"#29619b","BLOCKS":[{"MESSAGE":"The API will be available in update [B]im 24.0.0[/B]"}]}}' \
          https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/im.message.add

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"DIALOG_ID":"chat20921","MESSAGE":"Attachment with primary color","ATTACH":{"ID":1,"COLOR_TOKEN":"primary","COLOR":"#29619b","BLOCKS":[{"MESSAGE":"The API will be available in update [B]im 24.0.0[/B]"}]},"auth":"**put_access_token_here**"}' \
          https://**put_your_bitrix24_address**/rest/im.message.add

try {
          const response = await $b24.callMethod('im.message.add', {
            DIALOG_ID: 'chat20921',
            MESSAGE: 'Attachment with primary color',
            ATTACH: {
              ID: 1,
              COLOR_TOKEN: 'primary',
              COLOR: '#29619b',
              BLOCKS: [
                {
                  MESSAGE: 'The API will be available in update [B]im 24.0.0[/B]'
                }
              ]
            }
          });
        
          const { result } = response.getData();
          console.log(result);
        } catch (error) {
          console.error(error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'im.message.add',
                    [
                        'DIALOG_ID' => 'chat20921',
                        'MESSAGE' => 'Attachment with primary color',
                        'ATTACH' => [
                            'ID' => 1,
                            'COLOR_TOKEN' => 'primary',
                            'COLOR' => '#29619b',
                            'BLOCKS' => [
                                [
                                    'MESSAGE' => 'The API will be available in update [B]im 24.0.0[/B]'
                                ]
                            ]
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            print_r($result);
        } catch (Throwable $e) {
            error_log($e->getMessage());
        }

BX24.callMethod(
            'im.message.add',
            {
                DIALOG_ID: 'chat20921',
                MESSAGE: 'Attachment with primary color',
                ATTACH: {
                    ID: 1,
                    COLOR_TOKEN: 'primary',
                    COLOR: '#29619b',
                    BLOCKS: [
                        {
                            MESSAGE: 'The API will be available in update [B]im 24.0.0[/B]'
                        }
                    ]
                }
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error().ex);
                } else {
                    console.log(result.data());
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'im.message.add',
            [
                'DIALOG_ID' => 'chat20921',
                'MESSAGE' => 'Attachment with primary color',
                'ATTACH' => [
                    'ID' => 1,
                    'COLOR_TOKEN' => 'primary',
                    'COLOR' => '#29619b',
                    'BLOCKS' => [
                        [
                            'MESSAGE' => 'The API will be available in update [B]im 24.0.0[/B]'
                        ]
                    ]
                ]
            ]
        );
        
        print_r($result);

Short Form ATTACH

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

PHP

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

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

Short Version of 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 '{"DIALOG_ID":"chat20921","MESSAGE":"Text block","ATTACH":[{"MESSAGE":"The API will be available in update [B]im 24.0.0[/B]"}]}' \
          https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/im.message.add

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"DIALOG_ID":"chat20921","MESSAGE":"Text block","ATTACH":[{"MESSAGE":"The API will be available in update [B]im 24.0.0[/B]"}],"auth":"**put_access_token_here**"}' \
          https://**put_your_bitrix24_address**/rest/im.message.add

try {
          const response = await $b24.callMethod('im.message.add', {
            DIALOG_ID: 'chat20921',
            MESSAGE: 'Text block',
            ATTACH: [
              {
                MESSAGE: 'The API will be available in update [B]im 24.0.0[/B]'
              }
            ]
          });
        
          const { result } = response.getData();
          console.log(result);
        } catch (error) {
          console.error(error);
        }

try {
            $response = $b24Service
                ->core
                ->call(
                    'im.message.add',
                    [
                        'DIALOG_ID' => 'chat20921',
                        'MESSAGE' => 'Text block',
                        'ATTACH' => [
                            [
                                'MESSAGE' => 'The API will be available in update [B]im 24.0.0[/B]'
                            ]
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            print_r($result);
        } catch (Throwable $e) {
            error_log($e->getMessage());
        }

BX24.callMethod(
            'im.message.add',
            {
                DIALOG_ID: 'chat20921',
                MESSAGE: 'Text block',
                ATTACH: [
                    {
                        MESSAGE: 'The API will be available in update [B]im 24.0.0[/B]'
                    }
                ]
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error().ex);
                } else {
                    console.log(result.data());
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'im.message.add',
            [
                'DIALOG_ID' => 'chat20921',
                'MESSAGE' => 'Text block',
                'ATTACH' => [
                    [
                        'MESSAGE' => 'The API will be available in update [B]im 24.0.0[/B]'
                    ]
                ]
            ]
        );
        
        print_r($result);

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 Bitrix root: /company/personal/user/1/

Warning

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

Continue Learning

Formatting

About the Block Collection

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