API de conversation intelligence: ¿construir sobre la API REST de Bitrix24 o usar una API lista?

· Por , fundador de Aelo

Una API de conversation intelligence recibe una grabación de llamada o un chat y devuelve un análisis estructurado —puntuación de calidad, resumen, puntuaciones por parte de la conversación, probabilidad de venta—, no texto en bruto. Está una capa por encima de una API de voz a texto: transcripción, puntuación y almacenamiento corren a cargo del proveedor.

Aelo aparece a lo largo del texto porque lo construimos nosotros. La parte de Bitrix24 describe la API REST de la propia plataforma y vale elijas lo que elijas.

¿Qué es una API de conversation intelligence?

Es la capa que convierte una conversación en números y texto que un CRM o un informe pueden usar. Tres tipos de API se presentan como «analítica de llamadas», y devuelven cosas muy distintas:

APIRecibesTe queda por construir
API de voz a textoUna transcripciónPuntuación, rúbrica, almacenamiento, escritura en el CRM
API de LLM de propósito generalLo que pida el promptTranscripción, una rúbrica estable, almacenamiento
API de conversation intelligenceUn registro y su análisis, con un contrato fijoSolo la integración con tus sistemas

Lo que cuenta en producción es el contrato fijo: los mismos campos documentados para cada llamada y una puntuación que es la que muestra el propio producto, de modo que la API, el panel y tus informes coinciden. Con tu propio prompt, mantener estables el formato de salida y la puntuación al editar el prompt o cambiar de modelo es tarea tuya.

¿Qué hace falta para construir la analítica de llamadas de Bitrix24 sobre su API REST por tu cuenta?

Los pasos de abajo son el camino completo que sigue la propia app de Aelo para Bitrix24. Los pasos 1, 3, 7 y 8 llaman a la API REST de Bitrix24; los pasos 2 y 4–6 son tu propio receptor y tu pipeline de análisis; el paso 8 solo hace falta si quieres las llamadas anteriores a la integración.

  1. Saber que una llamada terminó. Registra una app (OAuth 2.0) y suscríbete con event.bind a ONCRMACTIVITYADD y ONCRMACTIVITYUPDATE. Una llamada saliente suele llegar ya completada en ADD; en una entrante, COMPLETED pasa a Y en UPDATE. Por eso la misma llamada puede llegar dos veces y necesitas una clave de idempotencia.
  2. Responder rápido. Si el handler responde con errores una y otra vez, Bitrix24 le baja la prioridad y al final lo desvincula, y la entrega para ese portal se detiene sin aviso. El receptor debe responder 200 al instante y dejar el trabajo en una cola.
  3. Llegar a la grabación. crm.activity.get te da los FILES de la actividad; disk.file.get convierte el id del archivo en un DOWNLOAD_URL. La grabación suele adjuntarse un tiempo después de que termina la llamada, así que reintenta durante un rato antes de concluir que no la hay. Descargar y guardar el audio también es cosa tuya.
  4. Transcribir con la API de voz a texto que elijas, y tratar aparte las llamadas sin grabación, las perdidas y las muy cortas.
  5. Eliminar los datos personales antes de que el texto llegue a un modelo de lenguaje: como mínimo teléfonos, emails y datos de pago.
  6. Puntuar. Escribe la rúbrica, el prompt y el análisis de la respuesta, y mantén las puntuaciones comparables de un mes a otro.
  7. Escribir el resultado de vuelta con crm.timeline.comment.add en el registro del CRM al que pertenece la llamada, o adjuntar la transcripción a la llamada con telephony.call.attachTranscription.
  8. Cubrir el pasado. Las llamadas hechas antes de la integración salen de crm.activity.list filtrado a actividades de llamada (PROVIDER_TYPE_ID: 'CALL'), no de los eventos.

Ningún paso es difícil por sí solo. Lo caro es mantener los ocho funcionando: renovación de tokens, reintentos, un portal que reinstala la app, una rúbrica que el equipo de ventas quiere cambiar.

¿Cuándo tiene sentido construirlo uno mismo?

Constrúyelo tú cuando el análisis es tu producto: necesitas control total sobre modelos, prompts y dónde se guarda cada byte, o vendes analítica a terceros. Usa una API de conversation intelligence lista cuando lo que necesitas son puntuaciones en el CRM e informes para un equipo de ventas, y el pipeline es un coste, no el objetivo.

¿Qué devuelve la API pública de Aelo?

Todos los endpoints están en https://api.aelo.cloud/api/public/v1 y aceptan una clave Bearer (aelo_sk_…). Solo el propietario de la organización puede emitir claves, en Configuración → Claves API; cada clave lleva uno o ambos permisos, records:write y records:read, y cada solicitud se limita a la organización que emitió la clave.

EndpointQué hace
POST /recordsCrea un registro desde un fileUrl (llamadas) o textContent (chats)
POST /records/uploadCrea un registro de llamada desde un archivo de audio subido
GET /recordsLista los registros, primero los más recientes
GET /records/{recordId}Devuelve un registro
GET /records/{recordId}/analysisDevuelve el último análisis de un registro
  • Análisis. Un resumen, qualityScore —el mismo número que el panel muestra para esa llamada—, seis puntuaciones de la rúbrica (saludo, detección de necesidades, claridad, manejo de objeciones, cierre, cortesía) y saleProbability en llamadas. Una métrica que el análisis no produjo es null, nunca un 0.
  • Idempotencia. Envía tu propio externalId y un reintento devuelve el registro original en lugar de crear otro.
  • Consulta. Mientras un registro no tiene análisis, analysis_not_found trae details.analysisExpected: true significa que el análisis aún llegará —en modo Manual, solo cuando alguien lo inicie en Aelo—; false, que el registro terminó sin análisis y no lo tendrá, por ejemplo una llamada por debajo de la duración mínima del proyecto.
  • Límites. 200 solicitudes por minuto por clave en cada endpoint; los límites de tamaño de las subidas están en la tabla de límites.
  • Plan. Starter y superiores.

La referencia completa está en la documentación de la API, y las dos formas de subir, en Subir llamadas y chats.

¿Necesitas la API si tus llamadas ya están en Bitrix24?

Normalmente no. La app de Aelo para Bitrix24 hace los pasos 1–7 sin código: en modo Automático recoge las llamadas terminadas y los chats de canales abiertos, los analiza y escribe el informe en el timeline del registro del CRM al que pertenece la llamada o el chat. Las conversaciones anteriores a la instalación no las recoge sola: el propietario de la organización importa el periodo que elija. La API pública es para todo lo demás: tu propia telefonía, un pipeline de datos o un CRM con el que Aelo todavía no se integra. Cómo se compara la app nativa con la IA integrada de Bitrix24 está en Aelo frente a BitrixGPT.

Preguntas frecuentes

¿Aelo es una API de conversation intelligence?

Sí. Aelo tiene una API REST pública en https://api.aelo.cloud/api/public/v1. Envías la grabación de una llamada (como archivo o como URL) o la transcripción de un chat y recibes el registro y su análisis: un resumen, una puntuación de calidad —el mismo número que muestra el panel—, seis puntuaciones de la rúbrica y, en llamadas, la probabilidad de venta. Las claves pertenecen a la organización y llevan los permisos records:write y records:read. Disponible desde el plan Starter.

¿Puedo obtener la transcripción de la llamada con la API de Aelo?

Hoy no. La API pública devuelve registros y su análisis —resumen, puntuación de calidad, puntuaciones de la rúbrica y probabilidad de venta—, pero no tiene un endpoint de transcripción. La transcripción queda en Aelo y, en la app de Bitrix24, además se adjunta a la propia llamada. Si tu pipeline necesita el texto en bruto, para esa parte la capa adecuada es una API de voz a texto.

¿Cuánto cuesta la API de Aelo?

La API pública está incluida desde el plan Starter; los planes de pago públicos empiezan en $59 al mes y se cobran por minutos analizados, no por llamada a la API. Las organizaciones del plan gratuito no pueden emitir claves. Cuando se agotan tanto los minutos incluidos como el saldo de créditos, una nueva subida se rechaza con insufficient_balance, y esa solicitud no guarda nada.

¿Qué métodos REST de Bitrix24 necesita un pipeline propio de analítica de llamadas?

Como mínimo: event.bind para ONCRMACTIVITYADD y ONCRMACTIVITYUPDATE, para saber que una llamada terminó; crm.activity.get y disk.file.get, para llegar a la grabación; crm.activity.list para las llamadas anteriores; y crm.timeline.comment.add o telephony.call.attachTranscription para escribir el resultado de vuelta. Transcripción, puntuación y almacenamiento quedan fuera de Bitrix24: hay que construirlos o comprarlos.

¿Puedo enviar chats a la API, no solo llamadas?

Sí. POST /records acepta un chat como textContent en lugar de fileUrl. Un chat muy largo se guarda pero no se analiza; los límites exactos de tamaño están en la referencia de la API. Un chat con muy pocos mensajes o sin respuesta del operador termina sin análisis, y la API lo indica en vez de dejarte consultando sin fin.