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

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

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

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

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

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

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

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

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

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

Шаг 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 МБ.

Файлом

Если публичной ссылки нет, прослойка скачивает файл сама и отправляет его методом /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 МБ. У одного звонка может быть несколько записей.

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

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

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

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

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

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

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

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

Лимиты