> 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.

# Clientevents

**Clientevents** zijn events op systeemniveau die van de server naar de client worden gestuurd om realtime communicatie mogelijk te maken. Deze events leveren audio, transcriptie, agentreacties en andere essentiële informatie aan de clientapplicatie.

> **Note**
>
> Zie de documentatie over [events van client naar server](/docs/nl/eleven-agents/customization/events/client-to-server-events) voor informatie over events die je van de client naar de server kunt sturen.

## Overzicht

Clientevents zijn essentieel om het realtime karakter van gesprekken te behouden. Ze bieden alles van initialisatiemetagegevens tot verwerkte audio en agentreacties.

> **Info**
>
> Deze events maken deel uit van het WebSocket-communicatieprotocol en worden automatisch verwerkt door onze
> SDK's. Inzicht hierin is cruciaal voor geavanceerde implementaties en debugging.

## Typen clientevents

#### conversation\_initiation\_metadata

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

```json
// 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
  }
}
```

#### queue\_status

* Alleen verzonden naar bellers die in de [oproepwachtrij](/docs/nl/eleven-agents/guides/call-queueing) 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

> **Note**
>
> Terwijl een beller in de wachtrij staat, komt wachtmuziek binnen als reguliere `audio`-events. Gebruik dit event om een
> wachtstatus weer te geven in plaats van de wachtmuziek als spraak van de agent te behandelen.

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

```javascript
// 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();
  }
});
```

#### ping

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

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

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

#### audio

* 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

> **Note**
>
> Via WebRTC-verbindingen wordt het `audio`-event niet verzonden, omdat audio rechtstreeks door LiveKit wordt verwerkt.

```json
// 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"
}
```

```javascript
// 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]);
  });
});
```

#### user\_transcript

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

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

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

#### agent\_response

* 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

> **Note**
>
> Gebruik het hieronder beschreven event `agent_chat_response_part` in plaats van op dit event te wachten
> om de tekst van de agent weer te geven terwijl deze wordt geproduceerd.

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

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

#### agent\_response\_correction

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

```json
// 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
  }
}
```

```javascript
// 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);
});
```

#### agent\_response\_metadata

* Bevat willekeurige metagegevens uit een custom LLM-response
* Alleen verzonden bij gebruik van een [custom LLM](/docs/nl/eleven-agents/customization/llm/custom-llm)
* Moet expliciet worden ingeschakeld in de `client_events`-configuratie van de agent

> **Note**
>
> Dit event is specifiek voor custom LLM-integraties. Hiermee kan je custom LLM-server
> aanvullende metagegevens samen met de response doorgeven die door de clientapplicatie kunnen worden gebruikt.

```json
// 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
  }
}
```

```javascript
// 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);
});
```

#### client\_tool\_call

* 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

> **Info**
>
> Als je de SDK gebruikt, zijn er callbacks beschikbaar om het resultaat terug te sturen naar de server.

```json
// 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"
      }
    }
  }
}
```

```javascript
// 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
    });
  }
});
```

#### agent\_tool\_response

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

```json
// 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
  }
}
```

```javascript
// 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}`);
  }
});
```

#### agent\_tool\_response\_full\_payload

* 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.

> **Warning**
>
> Dit event stelt het volledige toolresultaat beschikbaar aan de client en kan gevoelige gegevens bevatten. Schakel het alleen in wanneer de client vertrouwd is om de payload te verwerken. Resultaten groter dan 64 KB worden automatisch afgekort.

```json
// 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
  }
}
```

#### React

```tsx
// 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>
  );
}
```

#### JavaScript

```javascript
// Example agent tool response full payload handler (using @elevenlabs/client)
import { Conversation } from '@elevenlabs/client';

const conversation = await Conversation.startSession({
  agentId: 'agent_7101k5zvyjhmfg983brhmhkd98n6',
  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).`);
    }
  },
});
```

#### vad\_score

* 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

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

#### mcp\_tool\_call

* 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`.

```json
{
  "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
  }
}
```

#### agent\_chat\_response\_part

* 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

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

```json
// 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"
  }
}
```

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

```javascript
// 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

`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](/docs/nl/eleven-agents/customization/llm#reasoning-summary) 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.

> **Note**
>
> Dit event en de bijbehorende SDK-callback zijn experimenteel. Hun gedrag en vorm kunnen
> in elke release veranderen.

**`Eventpayload`**

```json title="Eventpayload" focus={3-7}
{
  "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.

**`Events voor redeneringen verwerken`**

```javascript title="Events voor redeneringen verwerken" focus={6-14}
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();
    }
  },
});
```

#### agent\_response\_complete

* 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

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

```javascript
// 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`);
});
```

#### guardrail\_triggered

* Wordt geactiveerd wanneer een schending van een [guardrail](/docs/nl/eleven-agents/best-practices/guardrails) 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.

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

```javascript
// 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.');
  },
});
```

## Eventstroom

Hier is een typische reeks gebeurtenissen tijdens een gesprek:

```mermaid
sequenceDiagram
    participant Client
    participant Server

    Server->>Client: conversation_initiation_metadata
    Note over Client,Server: Connection established
    Server->>Client: ping
    Client->>Server: pong
    Server->>Client: audio
    Note over Client: Playing audio
    Note over Client: User responds
    Server->>Client: user_transcript
    Server->>Client: audio
    Server->>Client: agent_response
    Server->>Client: client_tool_call
    Note over Client: Client tool runs
    Client->>Server: client_tool_result
    Server->>Client: audio
    Server->>Client: agent_response
    Note over Client: Playing audio
    Note over Client: Interruption detected
    Server->>Client: agent_response_correction

```

Wanneer een agent de gelijktijdigheidslimiet heeft bereikt en [oproepen in de wachtrij plaatsen](/docs/nl/eleven-agents/guides/call-queueing) is ingeschakeld, stuurt de server `queue_status`-events tussen `conversation_initiation_metadata` en het eerste `audio`-event. Wachtmuziek wordt als `audio`-events geleverd totdat de beller wordt toegelaten.

### Best practices

1. **Foutafhandeling**

   * Implementeer goede foutafhandeling voor elk eventtype
   * Log belangrijke events voor debugging
   * Ga netjes om met verbindingsonderbrekingen

2. **Audiobeheer**

   * Buffer audiochunks op de juiste manier
   * Implementeer goede opschoning bij onderbreking
   * Beheer audiobronnen

3. **Verbindingsbeheer**

   * Reageer snel op PING-events
   * Implementeer herverbindingslogica
   * Controleer de verbindingsstatus

## Problemen oplossen

#### Verbindingsproblemen

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

#### Audioproblemen

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

#### Eventverwerking

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

> **Info**
>
> Bekijk onze [SDK- documentatie](/docs/nl/eleven-agents/libraries/python) voor gedetailleerde implementatievoorbeelden.