BatchV3.make

Method for executing batch requests to Bitrix24 REST API version 3. Allows executing up to 50 commands in a single API call.

We are still updating this page. Some data may be missing here — we will complete it shortly.

Overview

Use BatchV3.make() to execute up to 50 REST API commands in a single request. This is especially useful when you need to retrieve or update large amounts of data while minimizing network requests and adhering to REST API limits.

// Basic usage
import { EnumCrmEntityTypeId } from '@bitrix24/b24jssdk'

const response = await $b24.actions.v3.batch.make({
  calls: [
    ['tasks.task.get', { id: 1 }],
    ['tasks.task.get', { id: 2 }]
  ],
  options: {
    isHaltOnError: true,
    returnAjaxResult: true,
    requestId: 'unique-request-id'
  }
})

Method Signature

make<T = unknown>(
  options: ActionBatchV3
): Promise<CallBatchResult<T>>

Parameters

The options object contains the following properties:

Parameter	Type	Required	Description
`calls`	`BatchCommandsArrayUniversal \| BatchCommandsObjectUniversal \| BatchNamedCommandsUniversal`	Yes	Commands to execute in the batch. Supports several formats.
`options`	`IB24BatchOptions`	No	Additional options for batch request execution.

Command Formats (`options.calls`)

1. Array of tuples (`BatchCommandsArrayUniversal`)

calls: [
  ['method1', params1],
  ['method2', params2],
  // ...
]

2. Array of objects (`BatchCommandsObjectUniversal`)

calls: [
  { method: 'method1', params: params1 },
  { method: 'method2', params: params2 },
  // ...
]

3. Object with named commands (`BatchNamedCommandsUniversal`)

calls: {
  command1: { method: 'method1', params: params1 },
  command2: ['method2', params2],
  // ...
}

Batch Request Options (`options.options`)

Option	Type	Default	Description
`isHaltOnError`	`boolean`	`true`	Whether to stop execution on the first error.
`returnAjaxResult`	`boolean`	`false`	Whether to return an `AjaxResult` object instead of data.
`requestId`	`string`	—	Unique request identifier for tracking. Used for request deduplication and debugging.

Return Value

Promise<CallBatchResult<T>> — a promise that resolves to a CallBatchResult<T> object.

The result structure depends on the input data format:

For array of commands: array of results in the same order.
For named commands: object with keys corresponding to command names.

Error Handling

Always check the result using isSuccess and handle errors:

const response = await $b24.actions.v3.batch.make({
  calls: [
    { method: 'tasks.task.get', params: { id: 1 } },
    { method: 'tasks.task.get', params: { id: 2 } }
  ],
  options: {
    isHaltOnError: true,
    returnAjaxResult: true,
    requestId: 'unique-request-id'
  }
})

if (!response.isSuccess) {
  // Handling error
  console.error(new Error(`Error: ${response.getErrorMessages().join('; ')}`))
  return
}

// Working with a successful result
const data = response.getData()

Examples

Getting Some Tasks

BatchTasks.ts

import type { AjaxResult } from '@bitrix24/b24jssdk'
import { B24Hook, EnumCrmEntityTypeId, LoggerFactory, SdkError } from '@bitrix24/b24jssdk'

type TaskItem = {
  id: number
  title: string
}

const devMode = typeof import.meta !== 'undefined' && (import.meta.dev || import.meta.env?.DEV)
const $logger = LoggerFactory.createForBrowser('Example:batchTasks', devMode)
const $b24 = B24Hook.fromWebhookUrl('https://your_domain.bitrix24.com/rest/1/webhook_code/')

async function getMultipleItems(itemIds: number[], requestId: string): Promise<TaskItem[]> {
  if (itemId.length < 1 || itemId.length > 50) {
    throw new SdkError({
      code: 'MY_APP_GET_PROBLEM'
      description: `The number of elements must be between 1 and 50`,
      status: 404
    })
  }

  const calls = itemIds.map(id => [
    'tasks.task.get',
    {
      id,
      select: ['id', 'title']
    }
  ])
  
  const response = await $b24.actions.v3.batch.make<{ item: TaskItem }>({
    calls,
    options: {
      isHaltOnError: true,
      returnAjaxResult: true,
      requestId
    }
  })
  
  if (!response.isSuccess) {
    throw new Error(`Problem: ${response.getErrorMessages().join('; ')}`)
  }
  
  const resultData = (response as Result<AjaxResult<{ item: TaskItem }>[]>).getData()
  const results: TaskItem[] = []
  resultData.forEach((resultRow, index) => {
    if (resultRow.isSuccess) {
      results.push(resultRow.getData()!.result.item)
    }
  })

  return results
}

// Usage
const requestId = 'batch/tasks.task.get'
try {
  const itemIds = [1, 2, 3]
  const items = await getMultipleItems(itemIds, requestId)
  
  $logger.info(`Retrieved ${items.length} items`, {
    expected: itemIds.length,
    retrieved: items.length,
    items: items.map(c => ({ id: c.id, title: c.title }))
  })
} catch (error) {
  if (error instanceof AjaxError) {
    $logger.critical(error.message, { requestId, code: error.code })
  } else {
    $logger.alert('Problem', { requestId, error })
  }
}

Alternatives and Recommendations

For sequential requests: Use Call for single calls.
For working with lists: Use CallList for retrieving large volumes of data.
For step-by-step processing: Use FetchList for processing data as it arrives.
To run more commands (more than 50): Use BatchByChunk, which automatically splits commands into chunks of 50.
On the client-side (browser): Use the built-in B24Frame object.