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
// 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
Информация о времени выполнения запроса
Обработка ошибок
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 | Пользователь не найден или неактивен |

