Trazas de OpenTelemetry

ElevenLabs Agents puede exportar conversaciones como trazas de OpenTelemetry codificadas como OTLP JSON (resourceSpans). Reenvíalas a Datadog, Grafana Tempo, Honeycomb o cualquier backend que procese OTLP.

Resumen

Exporta trazas desde tres superficies. Las tres comparten el mismo ID de traza por conversación y la nomenclatura de atributos elevenlabs.*. La estructura y los tiempos de los spans difieren entre post-llamada/GET (basado en transcripciones) y monitorización (basado en eventos).

Superficies de exportación

Elegir una superficie

• Todas las llamadas completadas en tu almacén de datos: webhook post-llamada
• Exportación o reparación puntual: GET de conversación con format=opentelemetry
• Interfaz de supervisión en directo o alertas: WebSocket de monitorización
• Cronología completa después de la llamada: webhook post-llamada o GET de conversación
• Eventos de herramientas, MCP o guardrails a medida que ocurren: WebSocket de monitorización

Usa traceId o elevenlabs.conversation_id para vincular datos entre superficies. Combina la monitorización para operaciones en directo, los webhooks para análisis duraderos y GET para rellenar datos.

Necesitas un recopilador compatible con OTLP o un proveedor de observabilidad para cada superficie. Los webhooks post-llamada requieren un endpoint de webhook del espacio de trabajo. La API GET y el WebSocket de monitorización tienen cada uno sus propios ámbitos de clave API y configuración; consulta las secciones siguientes.

Webhook post-llamada

Cuando finaliza una conversación, ElevenLabs envía una solicitud POST si hay configurado un webhook post-llamada, events incluye transcript y transcript_format es opentelemetry.

El type del webhook es post_call_transcription_otel (no post_call_transcription, que devuelve transcripciones JSON).

Carga útil del webhook

{
  "type": "post_call_transcription_otel",
  "event_timestamp": 1700000000,
  "data": {
    "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa",
    "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
    "otlp_traces": {
      "resourceSpans": []
    }
  }
}

Activar transcripciones de OpenTelemetry

Entrega

Estructura de la traza

Cada entrega es una traza completa: un span raíz y sus elementos secundarios.

elevenlabs.conversation
├── elevenlabs.recv.user_transcript
├── elevenlabs.recv.agent_response
│   └── elevenlabs.tool.{name}
└── ...

Los spans de respuesta del agente incluyen elevenlabs.reasoning_content cuando la entrega contiene un resumen del razonamiento.

La temporización procede de time_in_call_secs de la transcripción y de los metadatos de la llamada. El span raíz establece elevenlabs.source = post_call_webhook y el estado ERROR cuando la llamada no terminó con una desconexión normal del cliente.

GET de conversación

Solicita el formato OpenTelemetry en Obtener conversación para recibir el mismo objeto otlp_traces que el webhook post-llamada de OpenTelemetry, además del modelo completo de conversación.

GET /v1/convai/conversations/{conversation_id}?format=opentelemetry

Requiere una clave API con CONVAI_READ. Con format=json (predeterminado), se omite otlp_traces.

{
  "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa",
  "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "status": "done",
  "transcript": [],
  "otlp_traces": {
    "resourceSpans": []
  }
}

import os
from dotenv import load_dotenv
from elevenlabs import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))
conversation = elevenlabs.conversational_ai.conversations.get(
    conversation_id="conv_9001k1zph3fkeh5s8xg9z90swaqa",
    format="opentelemetry",
)
otlp_traces = conversation.otlp_traces

Los nombres de span esperados incluyen elevenlabs.conversation, elevenlabs.recv.user_transcript y elevenlabs.recv.agent_response.

WebSocket de monitorización

Transmite datos de trazas de OpenTelemetry como OTLP JSON mientras una conversación está en curso. Cada mensaje es un pequeño lote de resourceSpans, no una única traza al finalizar la llamada.

wss://api.elevenlabs.io/v1/convai/conversations/{conversation_id}/monitor?events_format=opentelemetry

La autenticación requiere CONVAI_WRITE, xi-api-key (o Authorization) y acceso EDITOR al espacio de trabajo del agente. Conéctate después de que comience la conversación.

Protocolo de sesión

1. Conéctate con encabezados de autenticación.
2. Recibe {"type": "connected"}.
3. Recibe un lote de span raíz (elevenlabs.conversation, elevenlabs.source = monitoring).
4. Recibe el historial en caché (aproximadamente los últimos 100 eventos) y, después, {"type": "history_complete"}.
5. Recibe lotes de spans en directo a medida que se producen los eventos.

Con events_format=json (predeterminado), el WebSocket devuelve eventos de cliente sin procesar en lugar de resourceSpans. Los comandos de control coinciden con Monitorización en tiempo real.

Estructura de la traza

elevenlabs.conversation
├── elevenlabs.turn.0
│   ├── elevenlabs.event.user_transcript
│   └── elevenlabs.tool.{name}
└── elevenlabs.turn.1

Los eventos estructurados se asignan a atributos específicos (por ejemplo, elevenlabs.user.text, elevenlabs.agent.text). Los eventos desconocidos usan elevenlabs.event.data con JSON truncado.

Ejemplo de conexión

import WebSocket from "ws";
const ws = new WebSocket(
  "wss://api.elevenlabs.io/v1/convai/conversations/conv_9001k1zph3fkeh5s8xg9z90swaqa/monitor?events_format=opentelemetry",
  {
    headers: {
      "xi-api-key": process.env.ELEVENLABS_API_KEY!,
    },
  }
);
ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.type === "connected" || msg.type === "history_complete") return;
  if (msg.resourceSpans) {
    forwardToCollector({ resourceSpans: msg.resourceSpans });
  }
});

Estructura de OTLP JSON

Las trazas de OpenTelemetry de todas las superficies comparten el mismo diseño de lote OTLP JSON:

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "elevenlabs-convai" } },
          {
            "key": "elevenlabs.conversation_id",
            "value": { "stringValue": "conv_9001k1zph3fkeh5s8xg9z90swaqa" }
          }
        ]
      },
      "scopeSpans": [
        {
          "scope": { "name": "elevenlabs.convai", "version": "1.0.0" },
          "spans": [
            {
              "traceId": "32_hex_chars",
              "spanId": "16_hex_chars",
              "name": "elevenlabs.recv.agent_response",
              "startTimeUnixNano": "1700000000000000000",
              "endTimeUnixNano": "1700000001000000000",
              "status": { "code": 1 }
            }
          ]
        }
      ]
    }
  ]
}

Limitaciones

• No se realiza envío directo a tu endpoint gRPC de OTLP.
• Las cargas útiles son JSON con formato de exportación OTLP, no protobuf sin procesar en la transmisión.

Documentación relacionada

• Webhooks post-llamada
• Monitorización en tiempo real