Ping.make() - Bitrix24 JS SDK

Overview

Use Ping.make() to measure the response time of Bitrix24 REST API. The method returns a Promise with a numeric value of the response time in milliseconds.

// Basic usage
const responseTime = await $b24.tools.ping.make()

if (responseTime >= 0) {
  console.log(`API response time: ${responseTime}ms`)
} else {
  console.error('Failed to measure API response time')
}

Method Signature

make(
  options?: { requestId?: string }
): Promise<number>

Parameters

Parameter	Type	Required	Description
`requestId`	`string`	No	Unique request identifier for tracking. Used for request deduplication and debugging.

Return Value

Promise<number> — a promise that resolves to a numeric value:

Positive number — response time in milliseconds from sending the request to receiving the response.
-1 — in case of error or timeout.

Ping.make() never throws. Network failures, HTTP errors, invalid credentials, and timeouts are all swallowed internally and surfaced as a return value of -1. There is no way to distinguish between failure modes from the call site — for that, use HealthCheck.make() or call the underlying method directly with CallV2.make() and inspect AjaxResult.

Examples

Measuring response time

import { B24Hook, LoggerFactory } from '@bitrix24/b24jssdk'

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

async function measureApiResponseTime(): Promise<number> {
  try {
    return await $b24.tools.ping.make({
      requestId: `unique-request-id`
    })
  } catch (error) {
    $logger.error('Ping failed unexpectedly', { error })
    return -1
  }
}

// Usage
try {
  const responseTime = await measureApiResponseTime()

  if (responseTime >= 0) {
    // Response time classification
    let status = 'optimal'
    if (responseTime > 1000) status = 'slow'
    if (responseTime > 3000) status = 'very_slow'
    if (responseTime > 10000) status = 'critical'

    $logger.info(`API response time: ${responseTime}ms (${status})`, {
      responseTime,
      status,
      threshold: 'Optimal < 1000ms'
    })
  } else {
    $logger.error('Failed to measure API response time')
  }
} catch (error) {
  $logger.error('Error measuring response time', { error })
}

Alternatives and Recommendations

For availability check: Use HealthCheck.
For measuring operation performance: Perform time measurements for specific API methods.
On the client-side (browser): Use the built-in B24Frame object.

HealthCheck

Method for checking the availability of Bitrix24 REST API. Performs a simple request to the REST API to verify service health.

Logger

Logger inspired by PHP Monolog, provides a structured logging system with support for channels, handlers, processors, and formatters. Implementation follows PSR-3 principles and the chain of responsibility pattern.