> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Rastreamentos do OpenTelemetry Os ElevenLabs Agents podem exportar conversas como **rastreamentos do OpenTelemetry** codificados como **JSON OTLP** (`resourceSpans`). Encaminhe-os para Datadog, Grafana Tempo, Honeycomb ou qualquer backend que receba OTLP. > **Info** > > A ElevenLabs não envia rastreamentos diretamente para seu coletor OTLP. Você recebe JSON no > formato OTLP de um webhook, API ou WebSocket de monitoramento e o encaminha para seu backend. ## 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 o tempo dos spans diferem entre pós-chamada/GET (baseados na transcrição) e monitoramento (baseado em eventos). ### Superfícies de exportação | Superfície | Quando você recebe os dados | Ideal para | | -------------------------- | ----------------------------------------------- | ---------------------------------------------------------- | | Webhook pós-chamada | Após o fim da conversa e a conclusão da análise | Pipelines em lote, faturamento e QA, armazenamento durável | | API GET de conversa | Sob demanda, após a criação da conversa | Preenchimento de dados, depuração, reprocessamento | | WebSocket de monitoramento | Durante uma conversa ao vivo | Painéis ao vivo, alertas, supervisão humana | ### Escolhendo uma superfície * **Todas as chamadas concluídas no seu data warehouse**: webhook pós-chamada * **Exportação ou reparo pontual**: GET de conversa com `format=opentelemetry` * **Interface de supervisão ao vivo ou alertas**: WebSocket de monitoramento * **Linha do tempo completa e detalhada depois da chamada**: webhook pós-chamada ou GET de conversa * **Eventos de ferramentas, MCP ou proteções à medida que acontecem**: WebSocket de monitoramento Use `traceId` ou `elevenlabs.conversation_id` para vincular dados entre as superfícies. Combine o monitoramento para operações ao vivo, webhooks para análises duráveis e GET para preenchimento de dados. Você precisa de um coletor ou fornecedor de observabilidade compatível com OTLP para cada superfície. Os 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 o término de uma conversa, 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 ```json { "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 #### Configurar pelo painel ### Criar um webhook do workspace No painel do ElevenAgents, crie um webhook do workspace com sua URL HTTPS e autenticação. ### Vincular o webhook pós-chamada Abra as [configurações dos Agents](https://elevenlabs.io/app/agents/settings), atribua o webhook como webhook pós-chamada, ative o evento **Transcript** e habilite **Payloads de transcrição do OpenTelemetry**. ![Configurações do webhook pós-chamada](/docs/_fern-img/eb5d768612d6461a21bc3127611f60724be3e1a55005af43faf48f2d7bf23807.webp) #### Configurar pela CLI > **Note** > > Os webhooks pós-chamada de todo o workspace são configurados na aba Painel ou API. Use a CLI para > substituir as configurações de webhook em um agente específico. ### Baixar a configuração do agente ```bash elevenlabs agents pull --agent "" ``` ### Editar `agent_configs/.json` Defina `platform_settings.workspace_overrides.webhooks`: ```json { "platform_settings": { "workspace_overrides": { "webhooks": { "post_call_webhook_id": "wh_01jqz7x8y9z0a1b2c3d4e5f6", "events": ["transcript"], "transcript_format": "opentelemetry" } } } } ``` ### Enviar suas alterações ```bash elevenlabs agents push --agent "" ``` #### Configurar pela API **`Python`** ```python title="Python" import os from dotenv import load_dotenv from elevenlabs import ElevenLabs load_dotenv() elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY")) elevenlabs.conversational_ai.settings.update( webhooks={ "post_call_webhook_id": "wh_01jqz7x8y9z0a1b2c3d4e5f6", "events": ["transcript"], "transcript_format": "opentelemetry", }, ) ``` **`TypeScript`** ```typescript title="TypeScript" import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY, }); await elevenlabs.conversationalAi.settings.update({ webhooks: { postCallWebhookId: "wh_01jqz7x8y9z0a1b2c3d4e5f6", events: ["transcript"], transcriptFormat: "opentelemetry", }, }); ``` Para um único agente, envie o mesmo objeto `webhooks` em `platform_settings.workspace_overrides` em [Atualizar agente](/docs/pt/api-reference/agents/update). > **Warning** > > Os webhooks de transcrição do OpenTelemetry não incluem áudio. Use `post_call_audio` se precisar > de gravações. > > Retorne **2xx** em caso de sucesso. **4xx** e **5xx** contam como falhas. > > As tentativas são aplicadas aos webhooks de transcrição (incluindo OpenTelemetry) e áudio somente quando **Ativar > novas tentativas** está habilitado para o webhook do workspace. Erros transitórios (\*\* 5xx \*\*, \*\*429 \*\*, \*\*408 \*\*) tentam novamente até > 5 vezes; **4xx** não. Falhas repetidas podem desativar o webhook automaticamente. Consulte > [Webhooks pós-chamada](/docs/pt/eleven-agents/workflows/post-call-webhooks) para ver detalhes e exceções da HIPAA. ### Entrega | Tópico | Detalhe | | ------------ | ---------------------------------------------------------------------------------------- | | Método | `POST` com corpo JSON | | Autenticação | `ElevenLabs-Signature: t={unix},v0={hmac}` sobre `{timestamp}.{body}` | | Tentativas | Exige **Ativar novas tentativas** no webhook; veja o aviso acima | | Tamanho | Parâmetros e resultados longos de ferramentas são truncados em 4 KB por atributo de span | ### Formato do rastreamento Cada entrega é um rastreamento completo: um span raiz mais spans filhos. ```text 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](/docs/pt/eleven-agents/customization/llm#reasoning-summary). 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](/docs/pt/api-reference/conversations/get) para receber o mesmo objeto `otlp_traces` do webhook OpenTelemetry pós-chamada, além do modelo completo da conversa. ```http GET /v1/convai/conversations/{conversation_id}?format=opentelemetry ``` Exige uma chave de API com `CONVAI_READ`. Com `format=json` (padrão), `otlp_traces` é omitido. ```json { "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa", "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6", "status": "done", "transcript": [], "otlp_traces": { "resourceSpans": [] } } ``` | Tópico | Detalhe | | --------------- | --------------------------------------------------------------------- | | Temporização | Mesmo gerador baseado em transcrição do webhook pós-chamada | | Transcrição | `transcript` ainda é retornado; `otlp_traces` é adicional | | URLs de arquivo | URLs assinadas nos atributos de span expiram após cerca de 15 minutos | **`Python`** ```python title="Python" 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 ``` **`TypeScript`** ```typescript title="TypeScript" import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY, }); const conversation = await elevenlabs.conversationalAi.conversations.get({ conversationId: "conv_9001k1zph3fkeh5s8xg9z90swaqa", format: "opentelemetry", }); const otlpTraces = conversation.otlpTraces; ``` **`cURL`** ```bash title="cURL" curl -s "https://api.elevenlabs.io/v1/convai/conversations/conv_9001k1zph3fkeh5s8xg9z90swaqa?format=opentelemetry" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ | jq '.otlp_traces.resourceSpans[0].scopeSpans[0].spans[].name' ``` Os nomes de span esperados incluem `elevenlabs.conversation`, `elevenlabs.recv.user_transcript` e `elevenlabs.recv.agent_response`. ## WebSocket de monitoramento > **Note** > > O monitoramento em tempo real exige um workspace Enterprise ou a flag de recurso `realtime-monitoring`. > Consulte [Monitoramento em tempo real](/docs/pt/eleven-agents/guides/realtime-monitoring) para configuração, > comandos de controle e requisitos de acesso. Transmita dados de rastreamento do OpenTelemetry como JSON OTLP enquanto uma conversa estiver em andamento. Cada mensagem é um pequeno lote `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 exige `CONVAI_WRITE`, `xi-api-key` (ou `Authorization`) e acesso **EDITOR** ao workspace do agente. Conecte-se após o início da conversa. ### Ativar o monitoramento no agente Defina `monitoring_enabled: true` e configure `monitoring_events` antes da chamada. Consulte [Monitoramento em tempo real](/docs/pt/eleven-agents/guides/realtime-monitoring#configuration). ### Conectar com o formato OpenTelemetry Adicione `events_format=opentelemetry` à URL do WebSocket de monitoramento. > **Warning** > > Eventos de VAD, probabilidade de turno e ping não ficam disponíveis quando `monitoring_events` personalizados são > configurados. O stream inclui apenas texto e metadados, não áudio bruto. ### Protocolo de 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), depois `{"type": "history_complete"}`. 5. Receba lotes de spans ao vivo à medida que 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](/docs/pt/eleven-agents/guides/realtime-monitoring#control-commands). ### Formato do rastreamento ```text elevenlabs.conversation ├── elevenlabs.turn.0 │ ├── elevenlabs.event.user_transcript │ └── elevenlabs.tool.{name} └── elevenlabs.turn.1 ``` | Aspecto | Pós-chamada e GET | Monitoramento | | --------------------- | ------------------------------------------ | --------------------------------------------------------- | | Granularidade | Um rastreamento por webhook ou solicitação | Muitas mensagens por conversa | | Spans de evento | Turnos da transcrição | `elevenlabs.event.{type}` | | Agrupamento de turnos | Implícito na ordem da transcrição | `elevenlabs.turn.N` explícito | | Ordem | Ordem estável da transcrição | Os eventos podem chegar fora de ordem cronológica estrita | 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. > **Info** > > Não presuma que a ordem dos eventos corresponde à ordem de fala. Correlacione spans ao vivo com dados pós-chamada usando > o mesmo `traceId`. ### Exemplo de conexão **`TypeScript`** ```typescript title="TypeScript" 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 }); } }); ``` **`Python`** ```python title="Python" import asyncio import json import os import websockets from dotenv import load_dotenv load_dotenv() async def monitor_opentelemetry(): uri = ( "wss://api.elevenlabs.io/v1/convai/conversations/conv_9001k1zph3fkeh5s8xg9z90swaqa/monitor" "?events_format=opentelemetry" ) headers = {"xi-api-key": os.getenv("ELEVENLABS_API_KEY")} async with websockets.connect(uri, extra_headers=headers) as ws: async for raw in ws: msg = json.loads(raw) if msg.get("type") in ("connected", "history_complete"): continue if msg.get("resourceSpans"): forward_to_collector({"resourceSpans": msg["resourceSpans"]}) asyncio.run(monitor_opentelemetry()) ``` ## Estrutura JSON OTLP Os rastreamentos do OpenTelemetry de todas as superfícies compartilham o mesmo layout de lote JSON 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 OTLP. * Os payloads são JSON no formato de exportação OTLP, não protobuf bruto em trânsito. ## Documentação relacionada * [Webhooks pós-chamada](/docs/pt/eleven-agents/workflows/post-call-webhooks) * [Monitoramento em tempo real](/docs/pt/eleven-agents/guides/realtime-monitoring)