API аналитики разговоров: собрать аналитику звонков на REST Bitrix24 или взять готовый API?

· Автор: , основатель Aelo

API аналитики разговоров (conversation intelligence API) принимает запись звонка или текст чата и возвращает не сырой текст, а структурированный анализ: оценку качества, резюме, оценки по отдельным частям разговора, вероятность сделки. Это слой над API распознавания речи: транскрипция, оценка и хранение идут на стороне поставщика, а вы забираете готовый результат.

Aelo упоминается здесь потому, что мы его сделали. Часть про Bitrix24 описывает собственный REST API платформы и верна при любом выборе.

Что такое API аналитики разговоров?

Это слой, который превращает разговор в числа и текст, пригодные для CRM и отчётов. «Аналитикой звонков» называют три разных вида API, и отдают они очень разное:

APIПолучаетеОстаётся собрать самому
API распознавания речиТранскриптОценку, карту оценки, хранение, запись в CRM
LLM API общего назначенияТо, о чём попросил промптТранскрипцию, стабильную карту оценки, хранение
API аналитики разговоровЗапись и её анализ в неизменном форматеТолько связку со своими системами

В работе решает именно неизменный формат: одни и те же задокументированные поля для каждого звонка и оценка — та же, что показывает сам продукт, так что API, дашборд и ваши отчёты сходятся. С собственным промптом держать формат ответа и оценку стабильными при правках промпта и смене модели — ваша задача.

Что нужно, чтобы собрать аналитику звонков на REST API Bitrix24 самому?

Шаги ниже — полный путь, которым идёт собственное приложение Aelo для Bitrix24. Шаги 1, 3, 7 и 8 вызывают REST API Bitrix24; шаги 2 и 4–6 — ваш собственный приёмник и конвейер анализа; шаг 8 нужен, только если нужны звонки, сделанные до интеграции.

  1. Узнать, что звонок закончился. Зарегистрировать приложение (OAuth 2.0) и подписаться через event.bind на ONCRMACTIVITYADD и ONCRMACTIVITYUPDATE. Исходящий звонок обычно приходит уже завершённым в ADD, у входящего COMPLETED становится Y в UPDATE. Поэтому один и тот же звонок может прийти дважды — нужен ключ идемпотентности.
  2. Отвечать быстро. Если обработчик раз за разом отвечает ошибкой, Bitrix24 понижает его приоритет, а потом отвязывает — и доставка по порталу молча прекращается. Приёмник должен сразу отвечать 200 и класть работу в очередь.
  3. Добраться до записи. crm.activity.get отдаёт FILES активности, disk.file.get превращает id файла в DOWNLOAD_URL. Запись часто прикрепляется не сразу после завершения звонка, поэтому какое-то время повторяйте попытки, прежде чем решить, что записи нет. Скачать и хранить аудио — тоже на вас.
  4. Распознать речь API распознавания на ваш выбор и отдельно обработать звонки без записи, пропущенные и совсем короткие.
  5. Вычистить персональные данные до того, как текст попадёт в языковую модель, — как минимум телефоны, email и платёжные данные.
  6. Оценить разговор. Написать карту оценки, промпт и разбор ответа и держать оценки сопоставимыми месяц к месяцу.
  7. Записать результат обратно через crm.timeline.comment.add в ту запись CRM, к которой относится звонок, или прикрепить транскрипт к звонку через telephony.call.attachTranscription.
  8. Охватить прошлое. Звонки, сделанные до появления интеграции, берутся из crm.activity.list с фильтром по звонкам (PROVIDER_TYPE_ID: 'CALL'), а не из событий.

Ни один шаг сам по себе не сложен. Дорого другое — держать работающими все восемь: обновление токенов, повторы, переустановку приложения на портале, карту оценки, которую отдел продаж хочет поменять.

Когда имеет смысл собирать самому?

Собирайте сами, когда анализ и есть ваш продукт: нужен полный контроль над моделями, промптами и тем, где хранится каждый байт, или вы продаёте аналитику другим. Берите готовый API аналитики разговоров, когда нужны оценки в CRM и отчёты для отдела продаж, а конвейер — это затраты, а не цель.

Что отдаёт публичный API Aelo?

Все методы находятся по адресу https://api.aelo.cloud/api/public/v1 и принимают ключ в заголовке Bearer (aelo_sk_…). Выпустить ключ может только владелец организации, в разделе Настройки → API-ключи; у ключа одно или оба права — records:write и records:read, — а каждый запрос ограничен организацией, выпустившей ключ.

МетодЧто делает
POST /recordsСоздаёт запись по fileUrl (звонки) или textContent (чаты)
POST /records/uploadСоздаёт запись звонка из загруженного аудиофайла
GET /recordsСписок записей, сначала новые
GET /records/{recordId}Одна запись
GET /records/{recordId}/analysisПоследний анализ записи
  • Анализ. Резюме, qualityScore — то же число, что дашборд показывает для этого звонка, — шесть оценок по пунктам (приветствие, выявление потребностей, ясность, работа с возражениями, закрытие, вежливость) и saleProbability для звонков. Метрика, которую анализ не дал, — null, а не 0.
  • Идемпотентность. Передайте свой externalId — и повторный запрос вернёт исходную запись, а не создаст вторую.
  • Опрос. Пока у записи нет анализа, ответ analysis_not_found несёт details.analysisExpected: true — анализ ещё будет (в режиме «Ручной» — только после того, как его запустят в Aelo), false — запись завершилась без анализа и уже не получит его, например звонок короче минимальной длины проекта.
  • Лимиты. 200 запросов в минуту на ключ для каждого метода; лимиты размера загружаемых файлов — в таблице лимитов.
  • Тариф. Starter и выше.

Полный справочник — в документации API, оба способа загрузки — в разделе «Загрузка звонков и чатов».

Нужен ли API, если звонки уже в Bitrix24?

Обычно нет. Приложение Aelo для Bitrix24 делает шаги 1–7 без кода: в режиме «Автоматический» само забирает завершённые звонки и чаты открытых линий, анализирует их и пишет отчёт в таймлайн той записи CRM, к которой относится звонок или чат. Разговоры, которые были до установки, само оно не забирает: выбранный период импортирует владелец организации. Публичный API — для всего остального: своей телефонии, конвейера данных или CRM, с которой у Aelo пока нет интеграции. Чем приложение отличается от встроенного AI Bitrix24, разобрано в сравнении Aelo и BitrixGPT.

Частые вопросы

Aelo — это API аналитики разговоров?

Да. У Aelo есть публичный REST API по адресу https://api.aelo.cloud/api/public/v1. Вы отправляете запись звонка (файлом или ссылкой) или текст чата и получаете запись и её анализ: резюме, оценку качества — то же число, что на дашборде, — шесть оценок по пунктам и для звонков вероятность сделки. Ключи привязаны к организации, права — records:write и records:read. Доступен на тарифе Starter и выше.

Можно ли получить транскрипт звонка через API Aelo?

Сейчас нет. Публичный API отдаёт записи и их анализ — резюме, оценку качества, оценки по пунктам и вероятность сделки, — но отдельного метода для транскрипта в нём нет. Транскрипт остаётся в Aelo, а в приложении для Bitrix24 он ещё и прикрепляется к самому звонку. Если вашему конвейеру нужен сырой текст, для этой части подходит API распознавания речи.

Сколько стоит API Aelo?

Публичный API входит в тарифы Starter и выше; платные тарифы начинаются от $59 в месяц и считаются по проанализированным минутам, а не по вызовам API. Организация на бесплатном тарифе ключи выпускать не может. Когда закончились и включённые минуты, и баланс кредитов, новая загрузка отклоняется с кодом insufficient_balance, и этот запрос ничего не сохраняет.

Какие методы REST Bitrix24 нужны для своей аналитики звонков?

Минимум такие: event.bind на ONCRMACTIVITYADD и ONCRMACTIVITYUPDATE, чтобы узнать о завершённом звонке; crm.activity.get и disk.file.get, чтобы добраться до записи; crm.activity.list для прошлых звонков; crm.timeline.comment.add или telephony.call.attachTranscription, чтобы записать результат обратно. Распознавание, оценка и хранение — вне Bitrix24: их нужно собрать или купить.

Можно ли отправлять в API чаты, а не только звонки?

Да. POST /records принимает чат как textContent вместо fileUrl. Очень длинный чат сохраняется, но не анализируется; точные лимиты размера — в справочнике API. Чат, где слишком мало сообщений или нет ответа оператора, завершается без анализа, и API прямо сообщает об этом, вместо того чтобы оставить вас опрашивать его без конца.