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