Add File to Chat im.disk.file.commit

{% 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: im

Who can execute the method: chat participant

{% note warning "Deprecated method" %}

The method is kept to support existing integrations. For new development, use im.v2.File.upload: it uploads a file to the chat in a single call, without uploading the file through Drive methods first.

{% endnote %}

The method im.disk.file.commit adds a file to a chat.

To add a file, specify:

one of the chat identifier parameters — CHAT_ID or DIALOG_ID
one of the file identifier parameters — FILE_ID or UPLOAD_ID

If multiple parameters are passed simultaneously, the method processes only the first one.

You can obtain the identifier of the new file after uploading it using the method disk.folder.upload.file. To get the identifier of an existing file, use:

disk.storage.getchildren — if the file is located in the root of the storage
disk.folder.getchildren — if the file is located in a folder

Method Parameters

{% include Note on required parameters %}

#| || Name type | Description || || CHAT_ID* integer | Identifier of the chat.

Required if DIALOG_ID is not provided || || DIALOG_ID* string | Identifier of the dialog in the format:

chatXXX — chat
sgXXX — group or project chat
XXX — user identifier for personal chat

Required if CHAT_ID is not provided || || FILE_ID* integer | Identifier of the file on Drive. An array can be passed.

Required if UPLOAD_ID is not provided || || UPLOAD_ID* integer | Identifier of the file on Drive. An array can be passed.

Supports an additional parameter AS_FILE, which allows sending the image without compression, as a file.

Required if FILE_ID is not provided || || MESSAGE string | Text message with the file || || SILENT_MODE string | Parameter for Open Channels chat

Possible values:

Y — send notification to the client
N — do not send notification to the client || || AS_FILE string | Send as a file. Only for UPLOAD_ID.

Possible values:

Y — yes
N — no || |#

Code Examples

{% include Note on Examples %}

{% list tabs %}

cURL (Webhook)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"CHAT_ID":1489,"FILE_ID":[5249,5250],"MESSAGE":"Project documents"}' \
  https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/im.disk.file.commit

cURL (OAuth)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"CHAT_ID":1489,"FILE_ID":[5249,5250],"MESSAGE":"Project documents","auth":"**put_access_token_here**"}' \
  https://**put_your_bitrix24_address**/rest/im.disk.file.commit

JS (TS)

// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

type FileUploadItem = {
  id: number
  chatId: number
  name: string
  extension: string
  size: number
  status: string
  authorId: number
  authorName: string
  urlPreview: string
  urlShow: string
  urlDownload: string
  isTranscribable: boolean
  isVideoNote: boolean
  isVoiceNote: boolean
}

type FileModelItem = {
  id: number
  name: string
  storageId: number
  size: number
  etag: string
  links: {
    download: string
    showInGrid: string
    preview: string
  }
}

// Shape of the payload returned in result (match the "response handling" section of the page)
type ImDiskFileCommitResult = {
  FILES: Record<string, FileUploadItem>
  DISK_ID: string[]
  FILE_MODELS: Record<string, FileModelItem>
  MESSAGE_ID: number
}

try {
  const response = await $b24.actions.v2.call.make<ImDiskFileCommitResult>({
    method: 'im.disk.file.commit',
    params: {
      CHAT_ID: 1489,
      FILE_ID: [5249, 5250],
      MESSAGE: 'Project documents',
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info(result.MESSAGE_ID, result.DISK_ID, result.FILES)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

JS (UMD)

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function commitFileToChat() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'im.disk.file.commit',
        params: {
          CHAT_ID: 1489,
          FILE_ID: [5249, 5250],
          MESSAGE: 'Project documents',
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info(result.MESSAGE_ID, result.DISK_ID, result.FILES)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', commitFileToChat)
</script>

PHP

try {
    $response = $b24Service
        ->core
        ->call(
            'im.disk.file.commit',
            [
                'CHAT_ID' => 1489,
                'FILE_ID' => [5249, 5250],
                'MESSAGE' => 'Project documents',
            ]
        );

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

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

BX24.js

BX24.callMethod(
    'im.disk.file.commit',
    {
        CHAT_ID: 1489,
        FILE_ID: [5249, 5250],
        MESSAGE: 'Project documents',
    },
    function(result)
    {
        if (result.error())
        {
            console.error(result.error());
        }
        else
        {
            console.log(result.data());
        }
    }
);

PHP CRest

require_once('crest.php');

$result = CRest::call(
    'im.disk.file.commit',
    [
        'CHAT_ID' => 1489,
        'FILE_ID' => [5249, 5250],
        'MESSAGE' => 'Project documents',
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';

// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "im.disk.file.commit", b24.Params{
	"CHAT_ID": 1489,
	"FILE_ID": []int{5249, 5250},
	"MESSAGE": "Project documents",
})
if err != nil {
	return fmt.Errorf("im.disk.file.commit: %w", err)
}

var item struct {
	MessageID b24.ID `json:"MESSAGE_ID"`
}
if err := json.Unmarshal(res.Result, &item); err != nil {
	return fmt.Errorf("parse response: %w", err)
}
fmt.Println(item.MessageID)

{% endlist %}

Response Handling

HTTP Status: 200

{
    "result": {
        "FILES": {
            "upload5249": {
                "id": 5249,
                "chatId": 1489,
                "date": {},
                "type": "file",
                "name": "image.png",
                "extension": "png",
                "size": 2144,
                "image": {
                    "height": 61,
                    "width": 72
                },
                "status": "done",
                "progress": 100,
                "authorId": 503,
                "authorName": "John Smith",
                "urlPreview": "https://mysite.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=5249&exact=N&_esd=hpbccd%2FZFlCVMvT8%2FoXYU%2FfMrCjiXqxIAf6V4Sv1rR0euQRiW7%2BsdhF7n1QGRL8ZBBmpuiVaX9sY2NbsyigTzBiykXGbFEbXUAmoPO8IvcdVkdoD5n6CJHZG9DZ0DRpH6i5goVbMdjo%3D&fileName=image.png",
                "urlShow": "https://mysite.com/bitrix/services/main/ajax.php?action=disk.api.file.showImage&SITE_ID=s1&humanRE=1&fileId=5249&width=1280&height=1280&signature=9f56cfa3412e55679012a6c3bef9ff391f1fc7becf6dc42bea2b8d68656934ce&exact=N&_esd=hpbccd%2FZFlCVMvT8%2FoXYU%2FfMrCjiXqxIAf6V4Sv1rR0euQRiW7%2BsdhF7n1QGRL8ZBBmpuiVaX9sY2NbsyigTzBiykXGbFEbXUAmoPO8IvcdVkdoD5n6CJHZG9DZ0DRpH6i5goVbMdjo%3D&fileName=image.png",
                "urlDownload": "https://mysite.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=5249&exact=N&_esd=hpbccd%2FZFlCVMvT8%2FoXYU%2FfMrCjiXqxIAf6V4Sv1rR0euQRiW7%2BsdhF7n1QGRL8ZBBmpuiVaX9sY2NbsyigTzBiykXGbFEbXUAmoPO8IvcdVkdoD5n6CJHZG9DZ0DRpH6i5goVbMdjo%3D&fileName=image.png",
                "viewerAttrs": {
                    "viewer": "",
                    "viewerType": "image",
                    "src": "https://mysite.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=5249&exact=N&_esd=hpbccd%2FZFlCVMvT8%2FoXYU%2FfMrCjiXqxIAf6V4Sv1rR0euQRiW7%2BsdhF7n1QGRL8ZBBmpuiVaX9sY2NbsyigTzBiykXGbFEbXUAmoPO8IvcdVkdoD5n6CJHZG9DZ0DRpH6i5goVbMdjo%3D&fileName=image.png",
                    "viewerResized": "",
                    "objectId": "5249",
                    "viewerGroupBy": "1489",
                    "imChatId": 1489,
                    "title": "image.png",
                    "actions": "[{\"type\":\"download\"},{\"type\":\"copyToMe\",\"text\":\"Save to Drive\",\"action\":\"BXIM.disk.saveToDiskAction\",\"params\":{\"fileId\":\"5249\"},\"extension\":\"disk.viewer.actions\",\"buttonIconClass\":\"ui-btn-icon-cloud\"}]"
                },
                "mediaUrl": {
                    "preview": {
                        "250": "https://mysite.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=5249&exact=N&_esd=hpbccd%2FZFlCVMvT8%2FoXYU%2FfMrCjiXqxIAf6V4Sv1rR0euQRiW7%2BsdhF7n1QGRL8ZBBmpuiVaX9sY2NbsyigTzBiykXGbFEbXUAmoPO8IvcdVkdoD5n6CJHZG9DZ0DRpH6i5goVbMdjo%3D&fileName=image.png"
                    }
                },
                "isTranscribable": false,
                "isVideoNote": false,
                "isVoiceNote": false
            }
        },
        "DISK_ID": [
            "5249"
        ],
        "FILE_MODELS": {
            "upload5249": {
                "id": 5249,
                "name": "image.png",
                "createTime": {},
                "updateTime": {},
                "deleteTime": null,
                "code": "media_original",
                "xmlId": null,
                "storageId": 663,
                "realObjectId": 5249,
                "parentId": 4821,
                "deletedType": 0,
                "createdBy": "503",
                "updatedBy": "503",
                "deletedBy": "0",
                "uniqueCode": "k7lj3sQxTRWSi6K93Vyh",
                "typeFile": 2,
                "globalContentVersion": 2,
                "fileId": 57077,
                "size": 2144,
                "etag": "73c045036a9e96943fa57316371655c2",
                "links": {
                    "download": "/bitrix/services/main/ajax.php?action=disk.file.download&SITE_ID=s1&fileId=5249",
                    "showInGrid": "/bitrix/tools/disk/focus.php?objectId=5249&action=showObjectInGrid&ncc=1",
                    "preview": "/bitrix/services/main/ajax.php?action=disk.api.file.showImage&SITE_ID=s1&humanRE=1&width=640&height=640&signature=8e152b3f4820b07a3f8ea79a6de60b0ae5a82a57467d08d1e8a8a399afb0330f&fileId=5249"
                }
            }
        },
        "MESSAGE_ID": 84779
    },
    "time": {
        "start": 1772451339,
        "finish": 1772451339.658828,
        "duration": 0.6588280200958252,
        "processing": 0,
        "date_start": "2026-03-02T14:35:39+01:00",
        "date_finish": "2026-03-02T14:35:39+01:00",
        "operating_reset_at": 1772451939,
        "operating": 0
    }
}

Returned Data

#| || Name type | Description || || result object | Root object of the result (detailed description) || || time time | Information about the execution time of the request || |#

Object result-item {#result-item}

#| || Name type | Description || || FILES object | Data of added files (detailed description) || || DISK_ID array | Array of file identifiers on Drive || || FILE_MODELS object | Models of added files on Drive (detailed description) || || MESSAGE_ID integer | Identifier of the message with files || |#

Object FILES {#files-item}

#| || Name type | Description || || upload{id} object | File object, where id — identifier of the upload file (detailed description) || |#

Object FILES.upload{id} {#files-upload-item}

#| || Name type | Description || || id integer | Identifier of the file on Drive || || chatId integer | Identifier of the chat || || date object | Date of file creation || || type string | Type of the item || || name string | Name of the file || || extension string | File extension || || size integer | Size of the file in bytes || || image object | Image parameters (detailed description) || || status string | Status of file processing || || progress integer | Progress of file processing in percentage || || authorId integer | Identifier of the file author || || authorName string | Name of the file author || || urlPreview string | Link to the file preview || || urlShow string | Link to view the file || || urlDownload string | Link to download the file || || viewerAttrs object | File viewer parameters (detailed description) || || mediaUrl object | Links to media file (detailed description) || || isTranscribable boolean | Is the file transcribable || || isVideoNote boolean | Is the file a video note || || isVoiceNote boolean | Is the file a voice note || |#

Object image {#files-upload-image}

#| || Name type | Description || || height integer | Height of the image || || width integer | Width of the image || |#

Object viewerAttrs {#files-upload-viewer-attrs}

#| || Name type | Description || || viewer string | Viewer identifier || || viewerType string | Type of viewer || || src string | Source file for the viewer || || viewerResized string | Source of the reduced version of the file || || objectId string | Identifier of the object in the viewer || || viewerGroupBy string | Identifier of the viewer group || || imChatId integer | Identifier of the chat for the viewer || || title string | Title in the viewer || || actions string | List of actions in the viewer in JSON string format || |#

Object mediaUrl {#files-upload-media-url}

#| || Name type | Description || || preview object | Set of links to file previews by size (detailed description) || |#

Object mediaUrl.preview {#files-upload-media-url-preview}

#| || Name type | Description || || 250 string | Link to preview with a width of 250 px || |#

Object FILE_MODELS {#file-models-item}

#| || Name type | Description || || upload{id} object | File model object, where id — identifier of the upload file (detailed description) || |#

Object FILE_MODELS.upload{id} {#file-models-upload-item}

#| || Name type | Description || || id integer | Identifier of the file on Drive || || name string | Name of the file || || createTime object | Date of file creation || || updateTime object | Date of file update || || deleteTime string | Date of file deletion, can be null || || code string | File type code || || xmlId string | External identifier, can be null || || storageId integer | Identifier of the storage || || realObjectId integer | Identifier of the real object || || parentId integer | Identifier of the parent folder || || deletedType integer | Deletion type || || createdBy string | Identifier of the creator || || updatedBy string | Identifier of the updater || || deletedBy string | Identifier of the deleter || || uniqueCode string | Unique code of the file || || typeFile integer | Numeric code of the file type || || globalContentVersion integer | Global content version || || fileId integer | Identifier of the related file || || size integer | Size of the file in bytes || || etag string | ETag of the file || || links object | Links for working with the file (detailed description) || |#

Object links {#file-models-upload-links}

#| || Name type | Description || || download string | Link to download the file || || showInGrid string | Link to show the file in the grid || || preview string | Link to preview the file || |#

Error Handling

HTTP Status: 400

{
    "error": "CHAT_ID_EMPTY",
    "error_description": "Chat ID can't be empty"
}

{% include notitle error handling %}

Possible Error Codes

#| || Status | Code | Description | Value || || 400 | CHAT_ID_EMPTY | Chat ID can't be empty | Possible reasons:

one of the required parameters CHAT_ID or DIALOG_ID is not provided
empty CHAT_ID is passed || || 400 | DIALOG_ID_EMPTY | Dialog ID can't be empty | Empty or invalid DIALOG_ID is passed || || 400 | FILES_ERROR | List of files is not specified | One of the required parameters FILE_ID or UPLOAD_ID is not provided || || 400 | SAVE_ERROR | Error during saving file to chat | Possible reasons:
FILE_ID or UPLOAD_ID is passed empty
non-existent file identifiers are passed || || 403 | ACCESS_ERROR | You do not have access to the specified dialog | Insufficient rights to view the dialog or a non-existent dialog is passed || |#

{% include system errors %}

Navigation Menu

Uh oh!

Add File to Chat im.disk.file.commit

Method Parameters

Code Examples

Response Handling

Returned Data

Object result-item {#result-item}

Object FILES {#files-item}

Object FILES.upload{id} {#files-upload-item}

Object image {#files-upload-image}

Object viewerAttrs {#files-upload-viewer-attrs}

Object mediaUrl {#files-upload-media-url}

Object mediaUrl.preview {#files-upload-media-url-preview}

Object FILE_MODELS {#file-models-item}

Object FILE_MODELS.upload{id} {#file-models-upload-item}

Object links {#file-models-upload-links}

Error Handling

Possible Error Codes

Continue Learning

Uh oh!

FilesExpand file tree

im-disk-file-commit.md

Latest commit

History

im-disk-file-commit.md

File metadata and controls

Add File to Chat im.disk.file.commit

Method Parameters

Code Examples

Response Handling

Returned Data

Object result-item {#result-item}

Object FILES {#files-item}

Object FILES.upload{id} {#files-upload-item}

Object image {#files-upload-image}

Object viewerAttrs {#files-upload-viewer-attrs}

Object mediaUrl {#files-upload-media-url}

Object mediaUrl.preview {#files-upload-media-url-preview}

Object FILE_MODELS {#file-models-item}

Object FILE_MODELS.upload{id} {#file-models-upload-item}

Object links {#file-models-upload-links}

Error Handling

Possible Error Codes

Continue Learning