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