Clientevents

• Automatisch verzonden bij het starten van een gesprek
• Initialiseert gespreksinstellingen en -parameters

// Example initialization metadata
{
  "type": "conversation_initiation_metadata",
  "conversation_initiation_metadata_event": {
    "conversation_id": "conv_123",
    "agent_output_audio_format": "pcm_44100",  // TTS output format
    "user_input_audio_format": "pcm_16000"    // ASR input format
  }
}

• Alleen verzonden naar bellers die in de oproepwachtrij staan terwijl de agent de concurrencylimiet heeft bereikt
• waiting wordt één keer verzonden, na conversation_initiation_metadata en vóór eventuele wachtmuziek
• admitted of timed_out wordt één keer verzonden wanneer het wachten eindigt. Na timed_out wordt de WebSocket gesloten met code 4300
• Altijd verzonden naar bellers in de wachtrij. Dit hoeft niet te worden ingeschakeld in de client_events-configuratie van de agent

// Example queue status event structure
{
  "type": "queue_status",
  "queue_status_event": {
    "status": "waiting"  // "waiting" | "admitted" | "timed_out"
  }
}

// Example queue status handler
websocket.on('queue_status', (event) => {
  const { status } = event.queue_status_event;
  if (status === 'waiting') {
    showWaitingState();
  } else if (status === 'admitted') {
    hideWaitingState();
  } else if (status === 'timed_out') {
    showAllAgentsBusyMessage();
  }
});

• Health check-event waarvoor onmiddellijk een reactie nodig is
• Automatisch verwerkt door de SDK
• Gebruikt om de WebSocket-verbinding te behouden

  // Example ping event structure
  {
    "ping_event": {
      "event_id": 123456,
      "ping_ms": 50  // Optional, estimated latency in milliseconds
    },
    "type": "ping"
  }

  // Example ping handler
  websocket.on('ping', () => {
    websocket.send('pong');
  });

• Bevat base64-gecodeerde audio voor afspelen
• Bevat een numerieke event-ID voor tracking en volgordebepaling
• Verwerkt streaming van spraakuitvoer
• Bevat uitlijningsgegevens met timinginformatie op tekenniveau

// Example audio event structure
{
  "audio_event": {
    "audio_base_64": "base64_encoded_audio_string",
    "event_id": 12345,
    "alignment": {  // Character-level timing data
      "chars": ["H", "e", "l", "l", "o"],
      "char_durations_ms": [50, 30, 40, 40, 60],
      "char_start_times_ms": [0, 50, 80, 120, 160]
    }
  },
  "type": "audio"
}

// Example audio event handler
websocket.on('audio', (event) => {
  const { audio_event } = event;
  const { audio_base_64, event_id, alignment } = audio_event;
  audioPlayer.play(audio_base_64);
  // Use alignment data for synchronized text display
  const { chars, char_start_times_ms } = alignment;
  chars.forEach((char, i) => {
    setTimeout(() => highlightCharacter(char, i), char_start_times_ms[i]);
  });
});

• Bevat afgeronde speech-to-textresultaten
• Vertegenwoordigt volledige uitingen van gebruikers
• Gebruikt voor gespreksgeschiedenis

// Example transcript event structure
{
  "type": "user_transcript",
  "user_transcription_event": {
    "user_transcript": "Hello, how can you help me today?"
  }
}

// Example transcript handler
websocket.on('user_transcript', (event) => {
  const { user_transcription_event } = event;
  const { user_transcript } = user_transcription_event;
  updateConversationHistory(user_transcript);
});

• Bevat het volledige bericht van de agent
• Wordt verzonden zodra dat bericht is voltooid, dus bij spraakgesprekken komt het meestal binnen nadat de audio van het bericht al is begonnen met streamen.
• Gebruikt voor weergave en geschiedenis

// Example response event structure
{
  "type": "agent_response",
  "agent_response_event": {
    "agent_response": "Hello, how can I assist you today?"
  }
}

// Example response handler
websocket.on('agent_response', (event) => {
  const { agent_response_event } = event;
  const { agent_response } = agent_response_event;
  displayAgentMessage(agent_response);
});

• Bevat het afgekorte antwoord na een onderbreking
• Werkt het weergegeven bericht bij
• Behoudt de nauwkeurigheid van het gesprek

// Example response correction event structure
{
  "type": "agent_response_correction",
  "agent_response_correction_event": {
    "original_agent_response": "Let me tell you about the complete history...",
    "corrected_agent_response": "Let me tell you about..."  // Truncated after interruption
  }
}

// Example response correction handler
websocket.on('agent_response_correction', (event) => {
  const { agent_response_correction_event } = event;
  const { corrected_agent_response } = agent_response_correction_event;
  displayAgentMessage(corrected_agent_response);
});

• Bevat willekeurige metagegevens uit een custom LLM-response
• Alleen verzonden bij gebruik van een custom LLM
• Moet expliciet worden ingeschakeld in de client_events-configuratie van de agent

// Example agent response metadata event structure
{
  "type": "agent_response_metadata",
  "agent_response_metadata_event": {
    "metadata": {
      // Any key-value pairs returned by your custom LLM
      "key": "value"
    },
    "event_id": 12345
  }
}

// Example metadata handler
websocket.on('agent_response_metadata', (event) => {
  const { agent_response_metadata_event } = event;
  const { metadata, event_id } = agent_response_metadata_event;
  // Use metadata for UI updates, logging, or analytics
  console.log(`Response ${event_id} metadata:`, metadata);
  updateResponseDetails(metadata);
});

• Vertegenwoordigt een functieaanroep die de agent door de client wil laten uitvoeren
• Bevat de toolnaam, tool call-ID en parameters
• Vereist dat de client de functie uitvoert en het resultaat terugstuurt naar de server

// Example tool call event structure
{
  "type": "client_tool_call",
  "client_tool_call": {
    "tool_name": "search_database",
    "tool_call_id": "call_123456",
    "parameters": {
      "query": "user information",
      "filters": {
        "date": "2024-01-01"
      }
    }
  }
}

// Example tool call handler
websocket.on('client_tool_call', async (event) => {
  const { client_tool_call } = event;
  const { tool_name, tool_call_id, parameters } = client_tool_call;
  try {
    const result = await executeClientTool(tool_name, parameters);
    // Send success response back to continue conversation
    websocket.send({
      type: "client_tool_result",
      tool_call_id: tool_call_id,
      result: result,
      is_error: false
    });
  } catch (error) {
    // Send error response if tool execution fails
    websocket.send({
      type: "client_tool_result",
      tool_call_id: tool_call_id,
      result: error.message,
      is_error: true
    });
  }
});

• Geeft aan wanneer de agent een toolfunctie heeft uitgevoerd
• Bevat toolmetagegevens en uitvoeringsstatus
• Geeft inzicht in het toolgebruik van de agent tijdens gesprekken

// Example agent tool response event structure
{
  "type": "agent_tool_response",
  "agent_tool_response": {
    "tool_name": "skip_turn",
    "tool_call_id": "skip_turn_c82ca55355c840bab193effb9a7e8101",
    "tool_type": "system",
    "is_error": false
  }
}

// Example agent tool response handler
websocket.on('agent_tool_response', (event) => {
  const { agent_tool_response } = event;
  const { tool_name, tool_call_id, tool_type, is_error } = agent_tool_response;
  if (is_error) {
    console.error(`Agent tool ${tool_name} failed:`, tool_call_id);
  } else {
    console.log(`Agent executed ${tool_type} tool: ${tool_name}`);
  }
});

• Spiegelt agent_tool_response en streamt daarnaast de volledige resultpayload van de tool als string in full_tool_result.
• Toont de tooluitvoer in de client voor weergave of verdere verwerking.
• Moet expliciet worden ingeschakeld in de client_events-configuratie van de agent.

// Example agent tool response full payload event structure
{
  "type": "agent_tool_response_full_payload",
  "agent_tool_response_full_payload": {
    "tool_name": "lookup_order",
    "tool_call_id": "lookup_order_c82ca55355c840bab193effb9a7e8101",
    "tool_type": "webhook",
    "is_error": false,
    "full_tool_result": "{\"order_id\": \"ORD-789\", \"status\": \"shipped\"}",
    "truncated": false
  }
}

// Example agent tool response full payload handler (using @elevenlabs/react)
import { ConversationProvider } from '@elevenlabs/react';
function App() {
  return (
    <ConversationProvider
      onAgentToolResponse={(response) => {
        if (!('full_tool_result' in response)) return;
        const { tool_name, tool_call_id, is_error, full_tool_result, truncated } = response;
        if (is_error) {
          console.error(`Agent tool ${tool_name} failed:`, tool_call_id);
        } else {
          console.log(`Tool ${tool_name} returned:`, full_tool_result);
        }
        if (truncated) {
          console.warn(`Tool ${tool_name} result was truncated (exceeded 64 KB).`);
        }
      }}
    >
      <Agent />
    </ConversationProvider>
  );
}

• Score-event voor Voice Activity Detection
• Geeft de waarschijnlijkheid aan dat de gebruiker spreekt
• Waarden lopen van 0 tot 1, waarbij hogere waarden een grotere zekerheid van spraak aangeven

// Example VAD score event
{
  "type": "vad_score",
  "vad_score_event": {
    "vad_score": 0.95
  }
}

• Geeft aan wanneer de agent een MCP-toolfunctie heeft uitgevoerd
• Bevat de toolnaam, tool call-ID en parameters
• Aangeroepen met een van vier statussen: loading, awaiting_approval, success en failure.

{
  "type": "mcp_tool_call",
  "mcp_tool_call": {
    "service_id": "xJ8kP2nQ7sL9mW4vR6tY",
    "tool_call_id": "call_123456",
    "tool_name": "search_database",
    "tool_description": "Search the database for user information",
    "parameters": {
      "query": "user information",
    },
    "timestamp": "2024-09-30T14:23:45.123456+00:00",
    "state": "loading",
    "approval_timeout_secs": 10
  }
}

• Streamt de antwoordtekst van de agent terwijl deze wordt gegenereerd, als berichten start, delta en stop
• Altijd verzonden in modus met alleen tekst; bij spraakgesprekken moet dit expliciet worden ingeschakeld in de client_events-configuratie van de agent
• Wordt niet verzonden terwijl de agent of een actieve procedure een blokkerende guardrail gebruikt, die het volledige antwoord moet evalueren voordat een deel ervan wordt vrijgegeven
• response_id identificeert het bericht dat wordt gestreamd en komt overeen met de response_id van de agent_response die het later vastlegt

// Example start event
{
  "type": "agent_chat_response_part",
  "text_response_part": {
    "type": "start",
    "text": "",
    "event_id": 12345,
    "response_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

// Example delta event with text chunk
{
  "type": "agent_chat_response_part",
  "text_response_part": {
    "type": "delta",
    "text": "Hello, how can I",
    "event_id": 12345,
    "response_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

// Example stop event
{
  "type": "agent_chat_response_part",
  "text_response_part": {
    "type": "stop",
    "text": "",
    "event_id": 12345,
    "response_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

// Example handler
websocket.on('agent_chat_response_part', (event) => {
  const { text_response_part } = event;
  const { type: partType, text, response_id } = text_response_part;
  if (partType === 'start') {
    initializeResponseBuffer(response_id);
  } else if (partType === 'delta') {
    appendToResponseBuffer(response_id, text);
  } else if (partType === 'stop') {
    finalizeResponse(response_id);
  }
});

agent_reasoning_response_part streamt door het model verstrekte redeneringen tijdens gesprekken met alleen tekst. Schakel het event in bij client_events en schakel Samenvatting van redeneringen in voor de agent. De server verzendt berichten start, delta en stop. Dit event wordt niet verzonden tijdens spraakgesprekken of wanneer de agent of een actieve procedure blokkerende guardrails gebruikt.

{
  "type": "agent_reasoning_response_part",
  "reasoning_response_part": {
    "type": "delta",
    "text": "The user asked to cancel, so I should verify the account before continuing.",
    "event_id": 123456
  }
}

Start- en stop-events gebruiken een lege text-waarde.

import { Conversation } from '@elevenlabs/client';
const conversation = await Conversation.startSession({
  agentId: 'agent_7101k5zvyjhmfg983brhmhkd98n6',
  textOnly: true,
  onAgentReasoningResponsePart: ({ type, text, event_id }) => {
    if (type === 'start') {
      initializeReasoningBuffer(event_id);
    } else if (type === 'delta') {
      appendToReasoningBuffer(text);
    } else if (type === 'stop') {
      finalizeReasoning();
    }
  },
});

• Wordt geactiveerd wanneer de agent de response heeft voltooid, inclusief eventuele openstaande tool calls. Na dit event produceert de agent alleen verdere uitvoer als de gebruiker nieuwe invoer geeft of een turn-time-out een nieuwe turn activeert.
• Moet expliciet worden ingeschakeld in de client_events-configuratie van de agent

// Example agent response complete event structure
{
  "type": "agent_response_complete",
  "agent_response_complete_event": {
    "event_id": 12345
  }
}

// Example handler
websocket.on('agent_response_complete', (event) => {
  const { agent_response_complete_event } = event;
  const { event_id } = agent_response_complete_event;
  console.log(`Agent response ${event_id} complete`);
});

• Wordt geactiveerd wanneer een schending van een guardrail het gesprek beëindigt. Wordt niet verzonden wanneer een guardrail een nieuwe poging activeert die slaagt.
• Het event zelf is het signaal: het bevat geen payload behalve het veld type.
• Moet expliciet worden ingeschakeld in de client_events-configuratie van de agent.

// Example guardrail triggered event structure
{
  "type": "guardrail_triggered"
}

// Example guardrail triggered handler (using @elevenlabs/client)
import { Conversation } from '@elevenlabs/client';
const conversation = await Conversation.startSession({
  agentId: 'agent_7101k5zvyjhmfg983brhmhkd98n6',
  onGuardrailTriggered: () => {
    console.warn('Guardrail triggered — conversation will end.');
  },
});

• Zorg voor een goede WebSocket-verbinding
• Controleer PING/PONG-reacties
• Controleer API-inloggegevens

• Controleer de verwerking van audiochunks
• Controleer de compatibiliteit van het audioformaat
• Controleer het geheugengebruik

• Log alle events voor debugging
• Implementeer foutgrenzen
• Controleer de registratie van eventhandlers