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

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`. Идентификатор можно получить методами: crm.contact.list crm.company.list crm.lead.list
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 (OAuth)

PHP

BX24.js

PHP CRest

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

try
        {
            const response = await $b24.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'
                }
            );
            
            const result = response.getData().result;
            console.log('Call registered:', result);
            processResult(result);
        }
        catch( error )
        {
            console.error('Error:', 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>';

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

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	Превышен лимит на интенсивность запросов
`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	Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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

Найти клиента в CRM по номеру телефона

Открыть карточку звонка у пользователя

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

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

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

Примеры кодаПримеры кода

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

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

Объект CRM_CREATED_ENTITIESОбъект CRM_CREATED_ENTITIES

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

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

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

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