Телефония: звонки, записи и расшифровка

Linkodium CRM принимает звонки от любой АТС через API. АТС сообщает о звонке, CRM находит заявку по номеру клиента или создаёт новую и показывает звонок с записью разговора в ленте заявки. Запись автоматически превращается в текст. Готовых кнопок «подключить АТС» в кабинете нет: между АТС и CRM нужен небольшой скрипт на вашем сервере, прослойка. Эта страница объясняет схему, а полное описание методов есть в документации API.

Как звонок попадает в CRM

1. АТС отправляет уведомление о событии звонка (вебхук) на адрес вашей прослойки.
2. Прослойка переводит его в запрос POST /api/v1/calls к CRM с API-ключом.
3. CRM ищет активную заявку с этим номером телефона (для входящего звонка созданную за последние 30 дней). Нашла: звонок попадает в её ленту. Не нашла: создаёт новую заявку.
4. Когда запись разговора готова, прослойка передаёт ссылку на неё или сам файл. CRM прикрепляет запись к звонку.

Каждое событие одного звонка (начало, конец, готовая запись) отправляется отдельным запросом с одним и тем же call_id: это идентификатор звонка в вашей АТС. Первый запрос заводит звонок, следующие дописывают итог, длительность и запись. Повтор одного и того же запроса ничего не портит.

Когда создаётся заявка

• Активной считается заявка со статусом «Новая заявка» или «В работе», не в архиве. Номера сравниваются по последним 10 цифрам; номер короче 10 цифр не сверяется.
• Входящий звонок с нового номера создаёт заявку (кроме ключа сотрудника без права «Создавать заявки»: такой звонок отклоняется, см. шаг 1): с телефоном клиента, источником (по умолчанию «Звонок») и менеджером по умолчанию в роли ответственного. Если менеджер по умолчанию не назначен, владелец компании. Если ключ выпущен на сотрудника, который видит только свои заявки, ответственным становится он сам. Сотрудники получают уведомление о новой заявке по своим настройкам.
• Исходящий звонок на номер без заявки по умолчанию не сохраняется. Чтобы он создавал заявку, включите галочку «Исходящий звонок на номер без заявки создаёт новую заявку»: «Настройки компании», вкладка «Компания», блок «Основное».

Отдельных уведомлений о звонках нет: звонок виден в ленте заявки.

Если подключены Яндекс Метрика или ДАРА Аналитика, первый входящий звонок заявки с разговором от 30 секунд уходит в них целью «Звонок от 30 с» (crm_call_target). Для этого прослойка должна передавать длительность разговора (duration) в событии конца звонка: Цели и правила конверсий.

Источник по номеру, на который звонили

Если на разных сайтах или в рекламе стоят разные номера, заведите их в «Настройки компании» -> «Трекинг», раздел «Телефонные номера»: у каждого номера свой сайт, источник и услуга. Прослойка передаёт в поле line номер, на который звонил клиент, и новая заявка из звонка получает источник и услугу этого номера. Порядок такой: source и service самого звонка, если прослойка их передала, затем строка номера, иначе источник «Звонок». Номера сравниваются по цифрам, запись +7 (342) 225-02-94 и 73422250294 одинакова. Там же у номера задаётся «Канал» (Реклама, Поиск, Соцсети, Карты, Переходы с сайтов, Прочее) для звонков, у которых визит на сайте не найден, а клик по номеру на сайте незадолго до звонка связывается с заявкой: Сквозная аналитика.

Звонок на номер с отметкой «Рекламный номер», который клиент набрал вручную (без клика по номеру на сайте), CRM связывает с посетителем из рекламы, если за 20 минут до звонка такой посетитель на сайте был ровно один. Если их несколько, звонок остаётся без визита с каналом «Реклама»: при сильном рекламном трафике так будет чаще, а точная привязка каждого звонка возможна только с пулом номеров (каждому посетителю свой номер), которого в CRM нет. Подробно: Сквозная аналитика, точность привязки.

Шаг 1. Выпустите API-ключ

1. Откройте «Настройки компании» -> «API-ключи».
2. В блоке «Выпустить ключ» введите «Название ключа», например «Телефония», выберите сотрудника (по умолчанию вы сами) и в «Областях доступа» отметьте «Звонки и записи разговоров от телефонии». Нажмите «Выпустить ключ».
3. Скопируйте ключ кнопкой «Скопировать» и сохраните в настройках прослойки. Затем нажмите «Готово, ключ сохранён».

Ключ работает с правами своего сотрудника, поэтому для телефонии всей компании выпускайте его владельцу или администратору. С ключом обычного сотрудника:

• без права «Создавать заявки» звонок с нового номера получает отказ 403 PERMISSION_DENIED и не сохраняется: ни заявки, ни звонка;
• при видимости «только свои» звонок в заявку коллеги сохраняется, но номер заявки в ответе не раскрывается (lead_number: null, hidden: true), а запись разговора к такому звонку не принимается;
• при видимости «только свои» новая заявка достаётся самому сотруднику, при видимости «все заявки компании» менеджеру по умолчанию, а если он не назначен, владельцу компании. Право «Менять ответственного» на это не влияет.

Шаг 2. Передавайте события звонка

Ключ передаётся в заголовке X-API-Key. Начало входящего звонка:

curl -X POST https://crm.linkodium.com/api/v1/calls \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "call_id": "1727517900.1234",
        "direction": "in",
        "client_phone": "+79991234567",
        "line": "+73422000000",
        "started_at": "2026-09-28T14:05:00+05:00"
      }'

Конец звонка, тот же call_id:

curl -X POST https://crm.linkodium.com/api/v1/calls \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "call_id": "1727517900.1234", "status": "answered", "duration": 185 }'

Шаг 3. Передайте запись разговора

Ссылкой

Если АТС отдаёт запись по ссылке, передайте её в поле record_url тем же call_id:

curl -X POST https://crm.linkodium.com/api/v1/calls \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "call_id": "1727517900.1234", "record_url": "https://records.example-pbx.com/abc123.mp3" }'

CRM скачает запись в течение нескольких минут и прикрепит её к звонку. Ссылка должна открываться из интернета без авторизации (подписанная ссылка АТС подходит) и жить не меньше нескольких часов. Форматы: mp3, wav, ogg, webm, m4a, aac, размер до 200 МБ. Формат CRM определяет по содержимому файла, а не по расширению в ссылке, так что ссылка без расширения (например, .../records/123/download) подходит. Если по ссылке пришёл не аудиофайл (страница ошибки или входа, JSON), это считается временной ошибкой скачивания: CRM повторит попытку, и после 5 неудачных попыток запись к звонку не прикрепляется.

Файлом

Если публичной ссылки нет, прослойка скачивает файл сама и отправляет его методом /api/v1/calls/recording. Звонок с этим call_id уже должен быть передан.

curl -X POST https://crm.linkodium.com/api/v1/calls/recording \
  -H "X-API-Key: $CRM_API_KEY" \
  -F "call_id=1727517900.1234" \
  -F "file=@/tmp/call-1727517900.1234.mp3"

Размер файла до 100 МБ. У одного звонка может быть несколько записей.

Что видно в карточке заявки

Звонок появляется в блоке «Лента событий» отдельной строкой:

• заголовок «Входящий звонок» или «Исходящий звонок»;
• «Телефон»: номер клиента;
• «Номер»: ваша линия, если АТС её передала;
• «Статус»: итог звонка по-русски, например «Принят», «Нет ответа», «Пропущен», «Занято»;
• «Длительность» и «Время звонка»;
• запись разговора: плеер для прослушивания и кнопка «Скачать запись».

Если заявку создал звонок, в ленте будет строка «Заявка создана по звонку». Записи могут слушать и скачивать только сотрудники вашей компании, которым видна заявка.

Расшифровка звонков

Записи разговоров автоматически превращаются в текст: речь распознаёт нейросеть. Текст появляется в карточке заявки под плеером записи, в блоке «Расшифровка». Разговор можно пробежать глазами, не слушая запись целиком, а коллега, который подхватывает клиента, быстро узнаёт, о чём договорились.

• Новая запись ставится на расшифровку сразу, как только CRM её получила. Пока идёт работа, в блоке написано «В очереди» или «Идёт расшифровка». Карточку обновлять не нужно: текст появится сам.
• Длинный текст свёрнут, полностью он открывается кнопкой «Показать полностью».
• Для записей, полученных до включения расшифровки, под плеером есть кнопка «Расшифровать». Её видит каждый сотрудник, которому видна заявка.
• Если расшифровать запись не удалось, в блоке будет причина: файл повреждён или в нём нет звука, запись длиннее 60 минут, файл не найден. Кнопка «Повторить» ставит запись на расшифровку ещё раз.
• Если в записи нет речи, в блоке будет «Речь в записи не распознана».
• Расшифровка доступна и через API: в ленте событий заявки у каждой записи звонка (документация API).

Как включить или выключить

Расшифровка включена по умолчанию. Управляет ей администратор:

1. Откройте «Настройки компании» -> вкладка «Компания».
2. В карточке «Расшифровка звонков» отметьте или снимите галочку «Расшифровывать звонки».
3. Нажмите «Сохранить».

Если выключить, новые записи не расшифровываются, а уже поставленные в очередь ждут, пока настройку не включат снова. Готовые тексты остаются в карточках. Текст хранится в CRM вместе с записью.

Пример для Novofon и Zadarma

Novofon и Zadarma сообщают о звонках вебхуками на адрес, который вы указываете в кабинете АТС. Прослойка принимает вебхук и переводит его в вызов CRM.

• В call_id передавайте pbx_call_id: он одинаков у всех событий одного звонка.
• client_phone передавайте в каждом событии, где номер есть: если первое событие потеряется, звонок заведёт следующее.
• call_start у этих АТС приходит без часового пояса. Прослойка должна дописать пояс, заданный в кабинете АТС.
• Ссылку на запись АТС готовит не сразу: Novofon советует запрашивать её примерно через 40 секунд после уведомления.
• Ответ 404 CALL_NOT_FOUND на событие записи исходящего звонка штатен, если настройка «Исходящий звонок на номер без заявки создаёт новую заявку» выключена: такой звонок не сохранялся.

Это учебное соответствие: проверьте названия полей и событий по документации своей АТС. Готовый пример прослойки на PHP, все поля, ответы и коды ошибок приведены в документации API.

АТС без вебхуков: опрос по API (UIS и другие)

Если АТС не присылает уведомления о звонках или в них нет ссылки на запись, прослойка может сама раз в минуту забирать журнал звонков через API АТС (например, у UIS это Data API, метод get.calls_report) и отправлять в CRM каждый новый или изменившийся звонок одним запросом POST /api/v1/calls:

• call_id: идентификатор звонка из журнала АТС, удобно с префиксом АТС (например, uis-123456789). Повтор того же звонка безопасен: CRM дописывает поля по тому же call_id.
• client_phone, line (номер, на который звонил клиент), direction, started_at с часовым поясом, status и duration из журнала.
• record_url: ссылка на запись разговора, которую АТС отдаёт в журнале или отдельным методом. Ссылка без расширения файла подходит; главное, чтобы она открывалась без входа в кабинет АТС. Если запись готова позже звонка, пришлите её следующим запросом с тем же call_id.
• Запоминайте, до какого момента журнал уже обработан, и спрашивайте с небольшим запасом назад (например, последние 3 часа): звонки, которые АТС дописала позже, тоже дойдут.

Лимиты