Skip to content

ElevenLabs · Conversaciones de Cobranza (API → BigQuery → dbt)

Trae las conversaciones del agente de voz de cobranza (ElevenLabs Conversational AI) a BigQuery vía la API, las aterriza en RAW y las modela en staging (solvento-adv-analytics-prod.elevenlabs) para que Analytics construya indicadores de cobranza (contactabilidad, promesa de pago, escalado, costo, etc.).

Estado — capa raw + stg lista; webhook e ingesta incremental push pendientes

Hoy la carga es por pull diario (Cloud Run que consulta la API: lista → detalle). Está pendiente implementar el post-call webhook para tener la data en near-real-time y capturar las llamadas fallidas (busy/no-answer) que el endpoint de lista no trae. El pull, además, es la red de seguridad del webhook cuando exista.

La data actual es mayormente de pruebas

Buena parte de las conversaciones cargadas son pruebas de playground (conversation_initiation_source = 'react_sdk') o llamadas que no llegaron a iniciar. Filtrar con is_playground_test = false / is_init_failed = false. Los KPIs recién tienen sentido con llamadas reales completas.

¿Llegaste hasta acá desde…?

Si ves… Eso sale de… La lógica está en…
Una conversación / llamada del agente de cobranza solvento-adv-analytics-prod.elevenlabs.stg_elevenlabs_conversations dbt-etls → models/advanced_analytics/elevenlabs/stg_elevenlabs_conversations.sql
El historial de mensajes de una llamada …elevenlabs.stg_elevenlabs_conversation_turns dbt-etls → …/stg_elevenlabs_conversation_turns.sql (unnest de transcript)
Si hubo promesa de pago / intención de recolocación Columnas dc_* de stg_elevenlabs_conversations (o stg_elevenlabs_data_collection) analysis.data_collection_results del RAW, pivoteado en dbt
El resultado de un criterio (escalado, satisfecho, …) Columnas eval_* (o stg_elevenlabs_evaluation_criteria) analysis.evaluation_criteria_results del RAW, en dbt
El dato crudo completo de una conversación (JSON) solvento-data-prod.elevenlabs.conversations_detail Cloud Run elevenlabs-extractor (sin lógica de negocio)
Campo Valor
Origen ElevenLabs Conversational AI — API GET /v1/convai/conversations (+ /{id})
Patrón Cloud Run agendado (pull incremental: lista → detalle → RAW append)
Destino RAW solvento-data-prod.elevenlabs.conversations_detail (+ conversations_list)
Destino stg solvento-adv-analytics-prod.elevenlabs.stg_elevenlabs_* (4 modelos)
Frecuencia Diaria (Cloud Scheduler POST /extract) · webhook near-real-time pendiente
Criticidad 🟡 Media (alimenta indicadores de un agente que llama clientes; volumen bajo)
Dueño Martin (data eng) · negocio/agente: María Sánchez · agente config: Leandro Gutiérrez
Repos elevenlabs-extractor · dbt-etls · terraform-gcp-infrastructure

Diagrama de linaje

graph LR
    SCH[["⏰ Cloud Scheduler<br/>diario · POST /extract"]]
    EL[["🤖 ElevenLabs<br/>Convai API"]]
    CR["Cloud Run<br/>elevenlabs-extractor<br/>(Flask · lista → detalle)"]
    RAW[("solvento-data-prod.elevenlabs<br/>conversations_detail<br/>(+ conversations_list)")]
    STG[("solvento-adv-analytics-prod.elevenlabs<br/>stg_elevenlabs_* (4)")]
    AN["Analytics<br/>(marts / KPIs de cobranza)"]

    SCH -->|dispara| CR
    EL -->|"xi-api-key · GET conversations (+ /{id})"| CR --> RAW -->|dbt-etls| STG --> AN

    classDef src fill:#fde68a,stroke:#b45309,color:#000;
    classDef store fill:#bfdbfe,stroke:#1e40af,color:#000;
    class SCH,EL src;
    class RAW,STG store;

Paso a paso

  1. ElevenLabs Convai — el agente "Agente de Cobranza - Solvento" atiende conversaciones (WhatsApp, Twilio, playground). El sistema le pasa contexto al iniciar vía dynamic variables (customer_rfc, amount_due, due_date, contact_mode, …).
  2. Cloud Scheduler (diario) hace POST /extract sobre el servicio.
  3. Cloud Run elevenlabs-extractor (repo, auth xi-api-key desde Secret Manager):
    • lista conversaciones paginando GET /v1/convai/conversations (incremental por call_start_after_unix = watermark − solapamiento).
    • por cada conversation_id nuevo, pide el detalle GET /v1/convai/conversations/{id} (saltea las ya done).
    • carga append en RAW: conversations_list (resumen) y conversations_detail (detalle, esquema híbrido: escalares + bloques JSON analysis / metadata / dynamic_variables / transcript / raw_payload). Sin lógica de negocio.
  4. dbt-etls (models/advanced_analytics/elevenlabs/) deduplica por conversation_id y arma las 4 stg (ver tabla). Los campos de analysis volátiles quedan accesibles vía JSON, así que sumar/quitar métricas en el agente no rompe la carga.
  5. Consumo: Analytics construye marts/KPIs sobre las stg.

Tablas que alimenta

Tabla Contenido Cómo se carga
elevenlabs.conversations_detail (RAW) Detalle por conversación (JSON híbrido) Cloud Run (append, dedup en dbt)
elevenlabs.conversations_list (RAW) Resumen del endpoint de lista Cloud Run (append)
elevenlabs.stg_elevenlabs_conversations 1 fila por conversación; escalares + dv_*/dc_*/eval_* + flags dbt-etls (table)
elevenlabs.stg_elevenlabs_conversation_turns 1 fila por turno (transcript) dbt-etls (table)
elevenlabs.stg_elevenlabs_data_collection Long: 1 fila por conversación × campo capturado dbt-etls (table)
elevenlabs.stg_elevenlabs_evaluation_criteria Long: 1 fila por conversación × criterio dbt-etls (table)

Consumo aguas abajo

  • Analytics — marts/KPIs de cobranza sobre las stg. Preguntas típicas que ya se responden:
    • Historial de mensajes de una conversación (stg_elevenlabs_conversation_turns).
    • Cuántas veces se llamó a un cliente y el resultado de cada llamada (stg_elevenlabs_conversations filtrando por dv_customer_rfc).
    • % de llamadas que generan promesa de pago (COUNTIF(dc_promesa_pago_establecida) sobre is_effective_contact).
    • Llamadas / clientes pendientes de generar promesa.
    • Evolución de un cliente llamada por llamada (ordenar por started_at; ARRAY_AGG de dc_promesa_pago_establecida).
  • Llave de cruce con la cartera: hoy es dv_customer_rfc. Falta que el agente envíe credito_id como dynamic variable (columna dv_credito_id ya lista, en coordinación con Leandro).

Si falla 🛠️

Impacto: los indicadores de cobranza quedan desactualizados (última corrida válida). No bloquea otros procesos de datos.

Síntoma Dónde mirar Acción
stg desactualizadas Job de Cloud Scheduler + logs del Cloud Run elevenlabs-extractor Ver si corrió; revisar el response de /extract (usar /preview para dry-run)
401/403 al llamar la API Logs Cloud Run Revisar el secret elevenlabs-extractor-api-key (Secret Manager) y su vigencia
RAW carga pero las stg vienen vacías/raras dbt-etls run Revisar dedup y los JSON_VALUE en models/advanced_analytics/elevenlabs/
KPIs "en cero" o unknown Tabla stg Casi todo es data de prueba/llamadas cortadas → filtrar is_playground_test/is_init_failed; validar con llamadas reales completas
Falta capturar busy/no-answer — Es esperado: requiere el post-call webhook (pendiente)

Escalación: extractor / stg / código → Martin · configuración del agente (data_collection, criterios, dynamic vars) → Leandro Gutiérrez · negocio / KPIs → María Sánchez.

Enlaces

Última actualización: 2026-07-20 · Pendiente: post-call webhook (near-real-time + llamadas fallidas). Si cambia el flujo, actualizar esta ficha en el mismo MR.