Traces OpenTelemetry

Les agents ElevenLabs peuvent exporter les conversations sous forme de traces OpenTelemetry encodées en OTLP JSON (resourceSpans). Transférez-les vers Datadog, Grafana Tempo, Honeycomb ou tout backend qui ingère OTLP.

Vue d’ensemble

Exportez les traces depuis trois sources. Elles partagent toutes le même ID de trace par conversation et la même nomenclature d’attributs elevenlabs.*. La structure et le minutage des spans diffèrent entre le post-appel/GET (basé sur la transcription) et le monitoring (basé sur les événements).

Sources d’exportation

Choisir une source

• Chaque appel terminé dans votre entrepôt de données : webhook post-appel
• Export ou correction ponctuels : GET de la conversation avec format=opentelemetry
• Interface de supervision en direct ou alertes : WebSocket de monitoring
• Chronologie complète a posteriori : webhook post-appel ou GET de la conversation
• Événements d’outil, MCP ou de garde-fou au moment où ils surviennent : WebSocket de monitoring

Utilisez traceId ou elevenlabs.conversation_id pour relier les données entre les sources. Combinez le monitoring pour les opérations en direct, les webhooks pour les analyses durables et GET pour le remplissage de données.

Vous avez besoin d’un collecteur compatible OTLP ou d’un fournisseur d’observabilité pour chaque source. Les webhooks post-appel nécessitent un endpoint de webhook du Workspace. L’API GET et le WebSocket de monitoring disposent chacun de leurs propres périmètres de clé API et de leur propre configuration, consultez les sections ci-dessous.

Webhook post-appel

Une fois une conversation terminée, ElevenLabs envoie une requête POST lorsqu’un webhook post-appel est configuré, que events inclut transcript et que transcript_format est défini sur opentelemetry.

Le type du webhook est post_call_transcription_otel et non post_call_transcription, qui renvoie des transcriptions JSON.

Charge utile du webhook

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

Activer les transcriptions OpenTelemetry

Livraison

Structure de la trace

Chaque livraison correspond à une trace complète : un span racine et des spans enfants.

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

Les spans de réponse de l’agent incluent elevenlabs.reasoning_content lorsque la livraison contient un résumé du raisonnement.

Le minutage provient de time_in_call_secs de la transcription et des métadonnées de l’appel. Le span racine définit elevenlabs.source = post_call_webhook et le statut ERROR lorsque l’appel ne s’est pas terminé par une déconnexion normale du client.

GET de la conversation

Demandez le format OpenTelemetry avec Obtenir une conversation pour recevoir le même objet otlp_traces que le webhook OpenTelemetry post-appel, ainsi que le modèle complet de la conversation.

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

Nécessite une clé API avec CONVAI_READ. Avec format=json (par défaut), otlp_traces est omis.

{
  "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

Les noms de span attendus incluent elevenlabs.conversation, elevenlabs.recv.user_transcript et elevenlabs.recv.agent_response.

WebSocket de monitoring

Diffusez les données de trace OpenTelemetry en OTLP JSON pendant qu’une conversation est en cours. Chaque message est un petit lot resourceSpans, et non une trace unique de fin d’appel.

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

L’authentification nécessite CONVAI_WRITE, xi-api-key (ou Authorization) et un accès EDITOR au Workspace de l’agent. Connectez-vous après le début de la conversation.

Protocole de session

1. Connectez-vous avec des en-têtes d’authentification.
2. Recevez {"type": "connected"}.
3. Recevez un lot de span racine (elevenlabs.conversation, elevenlabs.source = monitoring).
4. Recevez l’historique mis en cache, environ les 100 derniers événements, puis {"type": "history_complete"}.
5. Recevez des lots de spans en direct à mesure que les événements surviennent.

Avec events_format=json (par défaut), le WebSocket renvoie les événements clients bruts au lieu de resourceSpans. Les commandes de contrôle correspondent à Monitoring en temps réel.

Structure de la trace

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

Les événements structurés sont associés à des attributs dédiés, par exemple elevenlabs.user.text, elevenlabs.agent.text. Les événements inconnus utilisent elevenlabs.event.data avec du JSON tronqué.

Exemple de connexion

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 });
  }
});

Structure JSON OTLP

Les traces OpenTelemetry de toutes les sources partagent la même structure de lot JSON OTLP :

{
  "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 }
            }
          ]
        }
      ]
    }
  ]
}

Limites

• Aucun envoi direct vers votre endpoint OTLP gRPC.
• Les charges utiles sont du JSON au format d’export OTLP, et non du protobuf brut transmis sur le réseau.

Documentation associée

• Webhooks post-appel
• Monitoring en temps réel