← API и интеграции

Колтреон / CallTreckingOne API и интеграции CRM/телефоний для коллтрекинга

Документ описывает актуальный приём звонков из внешних CRM и телефоний в Колтреон / CallTreckingOne для коллтрекинга.

Главный принцип: внешний сервис передает факт звонка, а Колтреон / CallTreckingOne принимает звонок только если номер назначения совпал с активным сопоставлением номера, указанный в кабинете коллтрекинг. Это защищает кабинет от ситуации, когда телефония отправляет все звонки аккаунта, а в статистику должны попасть только звонки на номер сайта.

Подключение через кабинет

Откройте:

/integrations.php

В блоке «Быстрое подключение» нажмите нужного провайдера. Кнопка делает три вещи:

1. создает отдельный API-токен;

2. добавляет или проверяет сопоставление текущего номера аккаунта;

3. показывает готовый URL для вставки в CRM/телефонию.

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

Поддерживаемые endpoints

| Провайдер | Endpoint |

|---|---|

| Bitrix24 | `/api_v1/webhooks/bitrix24_call_end.php?token=TOKEN` |

| amoCRM / Kommo | `/api_v1/webhooks/amocrm.php?token=TOKEN` |

| Zadarma | `/api_v1/providers/zadarma.php?token=TOKEN` |

| Novofon | `/api_v1/providers/zadarma.php?provider=novofon&token=TOKEN` |

| Mango Office | `/api_v1/providers/mango.php?token=TOKEN` |

| UIS / CoMagic | `/api_v1/providers/uis.php?token=TOKEN` |

| Телфин | `/api_v1/providers/telfin.php?token=TOKEN` |

| Ростелеком ВАТС | `/api_v1/providers/rostelecom.php?token=TOKEN` |

| Своя CRM / любая телефония | `/api_v1/calls/import.php` + `Authorization: Bearer TOKEN` |

Bitrix24

Используйте событие окончания звонка `ONVOXIMPLANTCALLEND`. Обработчик принимает только входящие звонки. Поддерживаются поля:

• `CALL_ID` — внешний ID звонка;

• `CALL_TYPE` — тип звонка, входящие принимаются как `2` или `3`;

• `PHONE_NUMBER` — номер клиента;

• `PORTAL_NUMBER`, `LINE_NUMBER`, `called_phone` — номер компании / линия;

• `CALL_DURATION` — длительность разговора;

• `CALL_FAILED_CODE` — код результата, `200` считается успешным;

• `CALL_RECORD_URL` — ссылка на запись, если есть.

Если Bitrix24 не передает номер линии, CallTreckingOne не сможет безопасно понять, к какому сопоставлению относится звонок, и вернет:

{"success": true, "skip": "number_not_mapped"}

Это не ошибка сервера. Это защита от приема всех звонков портала.

amoCRM / Kommo

У amoCRM/Kommo нет одного универсального call-end webhook для всех телефоний. Часто звонки приходят через конкретный VoIP-виджет. Поэтому обработчик `amocrm.php` сделан гибким и принимает разные структуры:

• `call.id`, `call_id`, `talk.id`, `note.id`;

• `caller_phone`, `phone`, `call.phone`, `talk.phone`;

• `called_phone`, `line_phone`, `call.called_phone`, `to`;

• `duration`, `call.duration`, `talk.duration`;

• `recording_url`, `record_url`.

Важно: если amoCRM/Kommo или виджет телефонии не передает номер линии и длительность, используйте прямой webhook самой телефонии или универсальный API CallTreckingOne.

Zadarma / Novofon

Обработчик `zadarma.php` работает для Zadarma и Novofon. Для Novofon используйте параметр:

provider=novofon

Поддерживаются события:

• `NOTIFY_END` — финал входящего звонка;

• `NOTIFY_RECORD` — запись разговора, если прилетает отдельно;

• `NOTIFY_OUT_END` — исходящий, пропускается.

Основные поля:

• `pbx_call_id`, `call_id_with_prefix`, `call_id` — внешний ID;

• `caller_id` — номер клиента;

• `called_did`, `called_id`, `destination`, `did` — номер компании;

• `seconds`, `billsec`, `talk_duration`, `duration` — длительность;

• `disposition` — результат звонка;

• `recording`, `recording_url`, `record_url` — запись.

Mango Office

Endpoint:

/api_v1/providers/mango.php?token=TOKEN

Поддерживается финальный webhook звонка, в том числе формат коллтрекинга Mango:

• `webhookType=2` — конец звонка;

• `callId` / `call_id` / `entry_id` — ID звонка;

• `callerPhone`, `clientPhone`, `from` — номер клиента;

• `calledPhone`, `ctn`, `to`, `virtual_number` — номер компании;

• `dateStart`, `dateEnd` — время начала/окончания;

• `talkDuration`, `duration` — длительность;

• `callStatus`, `status` — статус.

Стартовые события не импортируются.

UIS / CoMagic

Endpoint:

/api_v1/providers/uis.php?token=TOKEN

Поддерживаются поля Data API / HTTP-уведомлений:

• `call_session_id`, `session_id`, `ext_id` — ID звонка;

• `direction` — направление;

• `calling_phone_number` — номер клиента;

• `called_phone_number` — номер компании;

• `start_time`, `finish_time` — время;

• `talk_duration` — длительность разговора;

• `is_lost` — потерянный звонок;

• `record_url`, `recording_url` — запись.

Телфин и Ростелеком ВАТС

Для этих провайдеров добавлены гибкие обработчики, потому что формат webhook у клиентов может отличаться в зависимости от тарифа, интеграционного модуля и промежуточного коннектора.

Endpoints:

/api_v1/providers/telfin.php?token=TOKEN
/api_v1/providers/rostelecom.php?token=TOKEN

Поддерживаемые имена полей:

• ID: `call_id`, `uuid`, `uid`, `session_id`;

• клиент: `caller_phone`, `caller`, `from`, `ani`, `a_number`, `src_num`;

• номер компании: `called_phone`, `called`, `to`, `dnis`, `b_number`, `dst_num`, `line_number`, `did`, `virtual_number`;

• время: `start_time`, `finish_time`, `started_at`, `ended_at`;

• длительность: `talk_duration`, `duration_sec`, `duration`, `billsec`, `seconds`;

• статус: `status`, `disposition`, `result`;

• запись: `record_url`, `recording_url`, `record`.

Универсальный API

Endpoint:

POST /api_v1/calls/import.php
Authorization: Bearer TOKEN
Content-Type: application/json

Пример:

{
  "source": "custom_crm",
  "provider": "custom",
  "external_call_id": "CALL-1001",
  "event_time": "2026-06-01T15:20:00+03:00",
  "direction": "in",
  "caller_phone": "+79990000000",
  "called_phone": "+74950000000",
  "duration_sec": 64,
  "is_missed": false,
  "strict_number_match": true,
  "recording_url": "https://example.ru/record.mp3"
}

Рекомендуется передавать `strict_number_match=true`, чтобы звонок был принят только при совпадении `called_phone` с активным сопоставлением.

Логика целевого звонка

Звонок считается целевым, если выполнены условия:

• направление входящее;

• звонок не пропущен;

• длительность не меньше 30 секунд;

• звонок связан с визитом сайта через `call_intents` / `client_id`;

• у пользователя подключена Метрика.

Если звонок не связан с визитом сайта, он сохраняется в кабинете, но не используется как целевая конверсия для Метрики.

Что заменять

В этом патче заменяются:

lib/ct_api_core.php
api_v1/providers/_webhook_helpers.php
api_v1/providers/zadarma.php
api_v1/providers/mango.php
api_v1/providers/uis.php
api_v1/providers/telfin.php
api_v1/providers/rostelecom.php
api_v1/webhooks/bitrix24_call_end.php
api_v1/webhooks/amocrm.php
integrations.php
docs/TECHNICAL_README.md
docs/TECHNICAL_README.php
api_v1/openapi.json

Не заменяйте рабочий `api_v1/providers/sipuni.php`, если он уже стоит и корректно показывает длительность.