Rastreios do OpenTelemetry

Os Agents da ElevenLabs podem exportar conversas como rastreamentos do OpenTelemetry codificados como OTLP JSON (resourceSpans). Encaminhe-os para Datadog, Grafana Tempo, Honeycomb ou qualquer backend que processe OTLP.

Visão geral

Exporte rastreamentos de três superfícies. Todas compartilham o mesmo ID de rastreamento por conversa e a nomenclatura de atributos elevenlabs.*. O formato e a temporização dos spans diferem entre pós-chamada/GET (baseados em transcrição) e monitoramento (baseado em eventos).

Superfícies de exportação

Escolhendo uma superfície

• Todas as chamadas concluídas no seu data warehouse: webhook pós-chamada
• Exportação ou correção pontual: GET de conversa com format=opentelemetry
• Interface de supervisão ao vivo ou alertas: WebSocket de monitoramento
• Linha do tempo completa após o ocorrido: webhook pós-chamada ou GET de conversa
• Eventos de ferramentas, MCP ou guardrails conforme acontecem: WebSocket de monitoramento

Use traceId ou elevenlabs.conversation_id para associar dados entre as superfícies. Combine o monitoramento para operações ao vivo, webhooks para análises duráveis e GET para preenchimento retroativo.

Você precisa de um coletor compatível com OTLP ou de um fornecedor de observabilidade para todas as superfícies. Webhooks pós-chamada exigem um endpoint de webhook do workspace. A API GET e o WebSocket de monitoramento têm, cada um, seus próprios escopos de chave de API e configuração; consulte as seções abaixo.

Webhook pós-chamada

Após uma conversa terminar, a ElevenLabs envia uma solicitação POST quando um webhook pós-chamada está configurado, events inclui transcript e transcript_format é opentelemetry.

O type do webhook é post_call_transcription_otel (não post_call_transcription, que retorna transcrições JSON).

Payload do webhook

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

Ativar transcrições do OpenTelemetry

Entrega

Formato do rastreamento

Cada entrega é um rastreamento completo: um span raiz e seus filhos.

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

Os spans de resposta do agente incluem elevenlabs.reasoning_content quando a entrega contém um resumo de raciocínio.

A temporização vem de time_in_call_secs da transcrição e dos metadados da chamada. O span raiz define elevenlabs.source = post_call_webhook e o status ERROR quando a chamada não terminou com uma desconexão normal do cliente.

GET de conversa

Solicite o formato OpenTelemetry em Obter conversa para receber o mesmo objeto otlp_traces do webhook pós-chamada do OpenTelemetry, além do modelo completo da conversa.

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

Requer uma chave de API com CONVAI_READ. Com format=json (padrão), otlp_traces é omitido.

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

Os nomes de span esperados incluem elevenlabs.conversation, elevenlabs.recv.user_transcript e elevenlabs.recv.agent_response.

WebSocket de monitoramento

Transmita dados de rastreamento do OpenTelemetry como OTLP JSON enquanto uma conversa está em andamento. Cada mensagem é um pequeno lote de resourceSpans, não um rastreamento único ao fim da chamada.

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

A autenticação requer CONVAI_WRITE, xi-api-key (ou Authorization) e acesso de EDITOR ao workspace do agente. Conecte-se após a conversa começar.

Protocolo da sessão

1. Conecte-se com cabeçalhos de autenticação.
2. Receba {"type": "connected"}.
3. Receba um lote de span raiz (elevenlabs.conversation, elevenlabs.source = monitoring).
4. Receba o histórico em cache (cerca dos últimos 100 eventos) e depois {"type": "history_complete"}.
5. Receba lotes de spans ao vivo conforme os eventos ocorrem.

Com events_format=json (padrão), o WebSocket retorna eventos brutos do cliente em vez de resourceSpans. Os comandos de controle correspondem a Monitoramento em tempo real.

Formato do rastreamento

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

Eventos estruturados são mapeados para atributos dedicados (por exemplo, elevenlabs.user.text, elevenlabs.agent.text). Eventos desconhecidos usam elevenlabs.event.data com JSON truncado.

Exemplo de conexão

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

Estrutura do OTLP JSON

Os rastreamentos do OpenTelemetry de todas as superfícies compartilham o mesmo layout 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 }
            }
          ]
        }
      ]
    }
  ]
}

Limitações

• Não há envio direto para seu endpoint gRPC do OTLP.
• Os payloads são JSON no formato de exportação OTLP, não protobuf bruto transmitido pela rede.

Documentação relacionada

• Webhooks pós-chamada
• Monitoramento em tempo real