Зарегистрировать звонок в Битрикс24 telephony.externalCall.register

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: telephony

Кто может выполнять метод: любой пользователь

Метод telephony.externalCall.register регистрирует внешний звонок в Битрикс24.

Для создания дела звонок необходимо также вызвать метод telephony.externalCall.finish

Метод работает только в контексте приложения

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

USER_ID*
integer

Идентификатор пользователя, для которого регистрируется звонок.

Идентификатор можно получить методом user.get

USER_PHONE_INNER*
string

Внутренний номер пользователя.

Внутренний номер можно получить методом user.get

Необходимо указать хотя бы один из параметров: USER_ID или USER_PHONE_INNER

PHONE_NUMBER*
string

Номер телефона клиента

TYPE*
integer

Тип звонка.

Возможные значения:

  • 1 — исходящий
  • 2 — входящий
  • 3 — входящий с перенаправлением
  • 4 — обратный звонок
  • 5 — информационный звонок

CALL_START_DATE
string

Дата и время начала звонка в формате ISO-8601 с указанием часового пояса, например 2026-03-07T10:20:30+03:00.

По умолчанию — текущее время на сервере

CRM_CREATE
integer

Автоматическое создание объекта CRM, если по номеру не найден подходящий объект.

Возможные значения:

  • 0 — не создавать
  • 1 — создавать

По умолчанию — 0.

Для исходящих звонков через внешнюю линию итоговое поведение также зависит от значения параметра CRM_AUTO_CREATE, заданного для линии в методах telephony.externalLine.add и telephony.externalLine.update

CRM_SOURCE
string

Идентификатор источника CRM (значение поля STATUS_ID).

Список значений можно получить методом crm.status.list с фильтром ENTITY_ID: 'SOURCE'

CRM_ENTITY_TYPE
string

Тип объекта CRM, с которым нужно связать звонок.

Возможные значения:

  • CONTACT — контакт
  • COMPANY — компания
  • LEAD — лид

CRM_ENTITY_ID
integer

Идентификатор объекта CRM из CRM_ENTITY_TYPE.

Идентификатор можно получить методами:

SHOW
integer

Показывать карточку звонка после регистрации.

Возможные значения:

  • 0 — не показывать
  • 1 — показывать

По умолчанию — 1

ADD_TO_CHAT
integer

Добавлять сообщение о звонке в чат сотрудника.

Возможные значения:

  • 0 — не добавлять
  • 1 — добавлять

По умолчанию — 1

CALL_LIST_ID
integer

Идентификатор списка обзвона, к которому привязывается звонок.

Если звонок инициирован из обзвона, передавайте идентификатор, полученный в событии ONEXTERNALCALLSTART.

Список доступных обзвонов можно получить методом crm.calllist.list

LINE_NUMBER
string

Номер внешней линии.

Номер линии можно получить методом telephony.externalLine.get.

Параметр не является обязательным, но рекомендуется передавать его всегда, особенно для входящих звонков, чтобы корректно работали привязка линии и отчеты/аналитика телефонии

EXTERNAL_CALL_ID
string

Внешний идентификатор звонка на стороне АТС/интеграции.

Рекомендуется передавать уникальное значение для каждого физического звонка, чтобы избежать возврата существующего CALL_ID при повторной регистрации в течение 30 минут

Особенности повторной регистрации

Если метод telephony.externalCall.register вызывается повторно в течение 30 минут, Битрикс24 может вернуть уже существующий CALL_ID вместо создания новой регистрации.

Для поиска существующей регистрации используются технические параметры звонка:

  • PHONE_NUMBER
  • TYPE
  • USER_ID или USER_PHONE_INNER
  • LINE_NUMBER (если передан)
  • EXTERNAL_CALL_ID (если передан)

Поиск выполняется в рамках приложения и только среди регистраций за последние 30 минут.

Поля CRM и времени старта не используются как ключ дедупликации:

  • CRM_ENTITY_TYPE
  • CRM_ENTITY_ID
  • CALL_START_DATE

Чтобы гарантированно зарегистрировать каждый физический звонок как отдельный, передавайте уникальный EXTERNAL_CALL_ID для каждого вызова на стороне АТС/интеграции.

В сценариях click-to-call, когда звонок создается самим Битрикс24, внутренний вызов регистрации выполняется без EXTERNAL_CALL_ID. Поэтому в статистике у таких звонков поле EXTERNAL_CALL_ID обычно пустое.

Примеры кода

Как использовать примеры в документации

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"USER_ID":1269,"PHONE_NUMBER":"79062195047","TYPE":2,"CRM_ENTITY_TYPE":"CONTACT","CRM_ENTITY_ID":797,"SHOW":1,"LINE_NUMBER":"3","EXTERNAL_CALL_ID":"asterisk-1710140185.18441","auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/telephony.externalCall.register
// 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

// Shape of the payload returned in result (match the "response handling" section of the page)
type ExternalCallRegisterResult = {
  CALL_ID: string
  CRM_CREATED_LEAD: number | null
  CRM_CREATED_ENTITIES: { ENTITY_TYPE: string; ENTITY_ID: number }[]
  CRM_ENTITY_TYPE: string
  CRM_ENTITY_ID: number
  LEAD_CREATION_ERROR?: string
}

try {
  const response = await $b24.actions.v2.call.make<ExternalCallRegisterResult>({
    method: 'telephony.externalCall.register',
    params: {
      USER_ID: 1269,
      PHONE_NUMBER: '79062195047',
      TYPE: 2,
      CRM_ENTITY_TYPE: 'CONTACT',
      CRM_ENTITY_ID: 797,
      SHOW: 1,
      LINE_NUMBER: '3',
      EXTERNAL_CALL_ID: 'asterisk-1710140185.18441',
    },
    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.CALL_ID, result.CRM_ENTITY_TYPE, result.CRM_ENTITY_ID)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
<!-- 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 registerExternalCall() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'telephony.externalCall.register',
        params: {
          USER_ID: 1269,
          PHONE_NUMBER: '79062195047',
          TYPE: 2,
          CRM_ENTITY_TYPE: 'CONTACT',
          CRM_ENTITY_ID: 797,
          SHOW: 1,
          LINE_NUMBER: '3',
          EXTERNAL_CALL_ID: 'asterisk-1710140185.18441',
        },
        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.CALL_ID, result.CRM_ENTITY_TYPE, result.CRM_ENTITY_ID)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', registerExternalCall)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.telephony.external_call.register(
        user_id=1269,
        phone_number="79062195047",
        call_type=2,
        crm_entity_type="CONTACT",
        crm_entity_id=797,
        show=1,
        line_number="3",
        external_call_id="asterisk-1710140185.18441",
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")
try {
    $response = $b24Service
        ->core
        ->call(
            'telephony.externalCall.register',
            [
                'USER_ID' => 1269,
                'PHONE_NUMBER' => '79062195047',
                'TYPE' => 2,
                'CRM_ENTITY_TYPE' => 'CONTACT',
                'CRM_ENTITY_ID' => 797,
                'SHOW' => 1,
                'LINE_NUMBER' => '3',
                'EXTERNAL_CALL_ID' => 'asterisk-1710140185.18441'
            ]
        );

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

    echo 'Success: ' . print_r($result, true);
    processData($result);

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error registering call: ' . $e->getMessage();
}
BX24.callMethod(
    "telephony.externalCall.register",
    {
        USER_ID: 1269,
        PHONE_NUMBER: '79062195047',
        TYPE: 2,
        CRM_ENTITY_TYPE: 'CONTACT',
        CRM_ENTITY_ID: 797,
        SHOW: 1,
        LINE_NUMBER: '3',
        EXTERNAL_CALL_ID: 'asterisk-1710140185.18441'
    },
    function(result)
    {
        if (result.error())
        {
            console.error(result.error(), result.error_description());
        }
        else
        {
            console.log(result.data());
        }
    }
);
require_once('crest.php');

$result = CRest::call(
    'telephony.externalCall.register',
    [
        'USER_ID' => 1269,
        'PHONE_NUMBER' => '79062195047',
        'TYPE' => 2,
        'CRM_ENTITY_TYPE' => 'CONTACT',
        'CRM_ENTITY_ID' => 797,
        'SHOW' => 1,
        'LINE_NUMBER' => '3',
        'EXTERNAL_CALL_ID' => 'asterisk-1710140185.18441'
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "telephony.externalCall.register", b24.Params{
	"USER_ID":          1269,
	"PHONE_NUMBER":     "79062195047",
	"TYPE":             2,
	"CRM_ENTITY_TYPE":  "CONTACT",
	"CRM_ENTITY_ID":    797,
	"SHOW":             1,
	"LINE_NUMBER":      "3",
	"EXTERNAL_CALL_ID": "asterisk-1710140185.18441",
})
if err != nil {
	return fmt.Errorf("telephony.externalCall.register: %w", err)
}

var item struct {
	CallID        string `json:"CALL_ID"`
	CRMEntityType string `json:"CRM_ENTITY_TYPE"`
	CRMEntityID   b24.ID `json:"CRM_ENTITY_ID"`
}
if err := json.Unmarshal(res.Result, &item); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println(item.CallID, item.CRMEntityType)

Обработка ответа

HTTP-статус: 200

{
    "result": {
        "CALL_ID": "externalCall.716f1cb73def9700a23842adf9c4c568.1773130779",
        "CRM_CREATED_LEAD": null,
        "CRM_CREATED_ENTITIES": [],
        "CRM_ENTITY_TYPE": "CONTACT",
        "CRM_ENTITY_ID": 797
    },
    "time": {
        "start": 1773130778,
        "finish": 1773130779.120838,
        "duration": 1.120837926864624,
        "processing": 1,
        "date_start": "2026-03-10T11:19:38+03:00",
        "date_finish": "2026-03-10T11:19:39+03:00",
        "operating_reset_at": 1773131378,
        "operating": 0.22185301780700684
    }
}

Возвращаемые данные

Название
тип

Описание

result
object

Корневой элемент ответа

CALL_ID
string

Идентификатор звонка

CRM_CREATED_LEAD
integer

Идентификатор автоматически созданного лида

CRM_CREATED_ENTITIES
array

Массив автоматически созданных объектов CRM

CRM_ENTITY_TYPE
string

Тип основного объекта CRM звонка

CRM_ENTITY_ID
integer

Идентификатор основного объекта CRM звонка

LEAD_CREATION_ERROR
string

Текст ошибки при автосоздании лида (если возникла)

time
time

Информация о времени выполнения запроса

Объект CRM_CREATED_ENTITIES

Название
тип

Описание

ENTITY_TYPE
string

Тип созданного объекта CRM

ENTITY_ID
integer

Идентификатор созданного объекта CRM

Обработка ошибок

HTTP-статус: 400, 403

{
    "error": "ERROR_CORE",
    "error_description": "Unknown TYPE"
}

Название
тип

Описание

error
string

Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания

error_description
error_description

Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

Возможные коды ошибок

Код

Описание

Значение

WRONG_AUTH_TYPE

Current authorization type is denied for this method

Метод вызван вне контекста приложения

ERROR_CORE

USER_ID or USER_PHONE_INNER should be set

Не переданы USER_ID и USER_PHONE_INNER

ERROR_CORE

Unknown TYPE

Передано недопустимое значение TYPE

ERROR_CORE

CALL_START_DATE should be in the ISO-8601 format

Некорректный формат CALL_START_DATE

ERROR_CORE

Unsupported phone number format

Некорректный формат PHONE_NUMBER

ERROR_CORE

User is not found or is not active

Пользователь не найден или неактивен

Статусы и коды системных ошибок

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически через 10 минут

405

ERROR_BATCH_METHOD_NOT_ALLOWED
Method is not allowed for batch usage

Текущий метод не разрешен для вызова с помощью batch

400

ERROR_BATCH_LENGTH_EXCEEDED
Max batch length exceeded

Превышена максимальная длина параметров, переданных в метод batch

401

NO_AUTH_FOUND
Wrong authorization data

Неверный access-токен или код вебхука

400

INVALID_REQUEST
Https required

Для вызовов методов требуется использовать протокол HTTPS

503

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24

403

ACCESS_DENIED
REST API is available only on commercial plans

REST API доступен только на коммерческих планах

403

INVALID_CREDENTIALS
Invalid request credentials

У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав

404

ERROR_MANIFEST_IS_NOT_AVAILABLE
Manifest is not available

Манифест недоступен

403

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более высоких привилегий, чем предоставляет токен вебхука

401

expired_token
The access token provided has expired

Предоставленный access-токен доступа истек

403

user_access_error
The user does not have access to the application

Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям

500

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение