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 прямо про це повідомляє, а не залишає вас опитувати його без кінця.