метод REST scope: telephony

telephony.externalCall.register

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

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

Описание

Метод 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 минут

Примеры запроса

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

Ответ

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

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

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

HTTP-статус: 400

{
    "error": "ERROR_CORE",
    "error_description": "Unknown TYPE"
}
Код Описание Значение
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 Пользователь не найден или неактивен

Что будем искать? Например,Продвижение

Этот сайт использует куки-файлы. Оставаясь на сайте, Вы соглашаетесь на их использование. Для получения дополнительной информации, пожалуйста, ознакомьтесь с политикой в отношении персональных данных.