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

# JavaScript SDK-referentie

Op deze pagina wordt de openbare API voor de Speech Engine JavaScript SDK (`@elevenlabs/elevenlabs-js`) beschreven.

## Een Speech Engine-resource ophalen

Haal een `SpeechEngineResource` op via de engine-ID. Het geretourneerde object biedt methoden om te koppelen aan een bestaande HTTP-server, een zelfstandige server te starten of afzonderlijke sessies te maken.

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();
const engine = await elevenlabs.speechEngine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6");
```

## SpeechEngineResource

### Eigenschappen

| Eigenschap | Type     | Beschrijving               |
| ---------- | -------- | -------------------------- |
| `engineId` | `string` | De ID van de spraakengine. |

### attach

Koppel aan een bestaande Node.js HTTP-server en begin Speech Engine-verbindingen te accepteren op het opgegeven pad. Gebruik dit als je al een HTTP-server hebt (bijvoorbeeld Express, Fastify of een gewone `http.createServer()`) en Speech Engine wilt toevoegen naast je bestaande routes.

Handelt WebSocket-upgrades, padrouting en requestverificatie automatisch af. Retourneert een `SpeechEngineAttachment` waarvan de methode `close()` geen nieuwe verbindingen meer accepteert zonder de HTTP-server te beïnvloeden.

```typescript
const attachment = engine.attach(httpServer, "/ws", {
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});
```

| Parameter    | Type                    | Beschrijving                                          |
| ------------ | ----------------------- | ----------------------------------------------------- |
| `httpServer` | `http.Server`           | De Node.js HTTP-server waaraan je koppelt.            |
| `path`       | `string`                | URL-pad waarop WebSocket-upgrades worden afgehandeld. |
| `handler`    | `SpeechEngineCallbacks` | Callbackobject (zie [Callbacks](#callbacks)).         |

Er is rechtstreeks op de client een snelkoppeling beschikbaar die `get()` en `attach()` in één aanroep combineert:

```typescript
await elevenlabs.speechEngine.attach("seng_8k3m9xr4hjnfg983brhmhkd98n6", httpServer, "/ws", {
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});
```

### verifyRequest

Controleer of een binnenkomend request afkomstig is van de ElevenLabs Speech Engine API. Controleert de header `X-Elevenlabs-Speech-Engine-Authorization` op een geldige JWT die is ondertekend met de SHA-256-hash van je API-sleutel.

Alleen nodig wanneer je de WebSocket-upgrade zelf beheert. Bij gebruik van `attach()` of `SpeechEngineServer` wordt de verificatie automatisch afgehandeld.

```typescript
const isValid = await engine.verifyRequest(req);
```

| Parameter | Type                                                           | Beschrijving                               |
| --------- | -------------------------------------------------------------- | ------------------------------------------ |
| `req`     | `{ headers: Record<string, string \| string[] \| undefined> }` | Object van het binnenkomende HTTP-request. |

**Retourneert:** `Promise<boolean>` — `true` als het request geldig is.

### createSession

Verpak een geaccepteerde WebSocket in een `SpeechEngineSession`. Gebruik dit voor aangepaste serverintegratie of handmatige WebSocket-afhandeling.

```typescript
const session = engine.createSession(ws, { debug: true });
session.on("user_transcript", (transcript, signal) => {
  /* ... */
});
```

| Parameter       | Type      | Standaard | Beschrijving                            |
| --------------- | --------- | --------- | --------------------------------------- |
| `ws`            | WebSocket |           | Een geaccepteerde WebSocket-verbinding. |
| `options.debug` | `boolean` | `false`   | Schakel debuglogging in.                |

**Retourneert:** `SpeechEngineSession`

## SpeechEngineServer

Een zelfstandige WebSocket-server die Speech Engine-verbindingen accepteert zonder een bestaande HTTP-server nodig te hebben. Gebruik deze wanneer je server uitsluitend bedoeld is voor het afhandelen van Speech Engine-verbindingen.

Gebruik [`engine.attach()`](#attach) voor integratie met een bestaande HTTP-server (bijvoorbeeld Express of Fastify).

```typescript
import { SpeechEngine } from "@elevenlabs/elevenlabs-js";

const server = new SpeechEngine.Server({
  port: 3001,
  debug: true,
  onTranscript(transcript, signal, session) {
    session.sendResponse(stream);
  },
});

server.start();
```

### Constructoropties

| Parameter  | Type                    | Standaard | Beschrijving                                                                                                                                                         |
| ---------- | ----------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `port`     | `number`                | `3001`    | Poort waarop wordt geluisterd.                                                                                                                                       |
| `apiKey`   | `string`                |           | ElevenLabs API-sleutel voor het verifiëren van verbindingen. Valt terug op de omgevingsvariabele `ELEVENLABS_API_KEY`. Niet vereist wanneer `disableAuth` `true` is. |
| `engineId` | `string`                |           | De ID van de spraakengine. Wordt automatisch ingevuld wanneer deze via de resource wordt gemaakt.                                                                    |
| ...        | `SpeechEngineCallbacks` |           | Alle callbackopties (`onInit`, `onTranscript`, `onClose`, `onDisconnect`, `onError`, `debug`, `disableAuth`). Zie [Callbacks](#callbacks).                           |

### start

Start de zelfstandige WebSocket-server op de geconfigureerde poort. Verifieert elke binnenkomende verbinding met de ElevenLabs API via de geconfigureerde API-sleutel, tenzij `disableAuth: true` is ingesteld.

```typescript
server.start();
```

### stop

Stop de WebSocket-server en sluit alle actieve verbindingen.

```typescript
await server.stop();
```

### handleConnection

Verpak een bestaande WebSocket in een `SpeechEngineSession` met de callbacks van de server gekoppeld. Gebruik dit als je je eigen WebSocket-server beheert en afzonderlijke verbindingen wilt verpakken.

```typescript
const session = server.handleConnection(ws);
```

| Parameter | Type        | Beschrijving                            |
| --------- | ----------- | --------------------------------------- |
| `ws`      | `WebSocket` | Een geaccepteerde WebSocket-verbinding. |

**Retourneert:** `SpeechEngineSession`

## SpeechEngineSession

Verpakt één WebSocket-verbinding. Elke verbinding vertegenwoordigt één gesprek. De sessie geeft events af voor transcripts en wijzigingen in de levenscyclus, en biedt methoden om LLM-antwoorden terug te sturen.

Wanneer er een nieuw transcript binnenkomt, wordt het abort-signaal van de vorige transcripthandler geactiveerd, waardoor lopende LLM-aanroepen worden onderbroken.

### Eigenschappen

| Eigenschap       | Type      | Beschrijving                                                         |
| ---------------- | --------- | -------------------------------------------------------------------- |
| `conversationId` | `string`  | De gespreks-ID die door de API is toegewezen. Beschikbaar na `init`. |
| `isOpen`         | `boolean` | Of de sessie nog open is.                                            |

### on

Registreer een handler voor een event. Retourneert de sessie voor chaining.

```typescript
session.on("user_transcript", (transcript, signal) => {
  /* ... */
});
```

### off

Verwijder een eerder geregistreerde handler.

```typescript
session.off("user_transcript", listener);
```

### once

Registreer een handler die één keer wordt uitgevoerd en zichzelf vervolgens verwijdert.

```typescript
session.once("init", (conversationId) => {
  /* ... */
});
```

### sendResponse

Stuur een LLM-antwoord terug naar de Speech Engine API voor text-to-speechsynthese. Moet binnen een `onTranscript`-handler worden aangeroepen. Als je deze buiten een handler aanroept, wordt een waarschuwing gegeven en keert de methode terug zonder iets te verzenden.

```typescript
// String response
session.sendResponse("Hello, how can I help?");

// Streamed response (OpenAI, Anthropic, or Gemini)
const stream = await openai.responses.create(
  { model: "gpt-4o", input: messages, stream: true },
  { signal }
);
session.sendResponse(stream);
```

| Parameter  | Type                                 | Beschrijving                                                                   |
| ---------- | ------------------------------------ | ------------------------------------------------------------------------------ |
| `response` | `string` \| `AsyncIterable<unknown>` | Een volledige string of een async iterable met tekstchunks / LLM-streamevents. |

De SDK detecteert automatisch tekst in de volgende LLM-streamformaten en extraheert deze:

| Provider                | Eventformaat                                                                   |
| ----------------------- | ------------------------------------------------------------------------------ |
| OpenAI Responses API    | `{ type: "response.output_text.delta", delta: "text" }`                        |
| OpenAI Chat Completions | `{ choices: [{ delta: { content: "text" } }] }`                                |
| Anthropic Messages API  | `{ type: "content_block_delta", delta: { type: "text_delta", text: "text" } }` |
| Google Gemini API       | `{ candidates: [{ content: { parts: [{ text: "text" }] } }] }`                 |

### close

Sluit de sessie en de onderliggende WebSocket-verbinding.

```typescript
session.close();
```

## SpeechEngineAttachment

Geretourneerd door `engine.attach()`. Beheert de levenscyclus van de WebSocket-server zonder de HTTP-server waaraan deze is gekoppeld te beïnvloeden.

### close

Stop met het accepteren van nieuwe verbindingen, verwijder de upgradelistener van de HTTP-server en sluit de onderliggende WebSocket-server.

```typescript
await attachment.close();
```

## Callbacks

Het callbackobject dat wordt doorgegeven aan `attach()` of `SpeechEngineServer`. Alle callbacks zijn optioneel.

| Callback       | Handtekening                                                                       | Beschrijving                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `onInit`       | `(conversationId: string, session: Session) => void`                               | Sessie geïnitialiseerd met een gespreks-ID.                                                                           |
| `onTranscript` | `(transcript: TranscriptMessage[], signal: AbortSignal, session: Session) => void` | Spraak van de gebruiker getranscribeerd.                                                                              |
| `onClose`      | `(session: Session) => void`                                                       | Schone verbinding verbroken door ElevenLabs.                                                                          |
| `onDisconnect` | `(session: Session) => void`                                                       | WebSocket onverwacht verbroken.                                                                                       |
| `onError`      | `(error: Error, session: Session) => void`                                         | Protocol- of WebSocket-fout.                                                                                          |
| `debug`        | `boolean`                                                                          | Schakel debuglogging in.                                                                                              |
| `disableAuth`  | `boolean`                                                                          | Sla JWT-verificatie bij binnenkomende verbindingen over. Zie [Authenticatie uitschakelen](#disabling-authentication). |

De `onTranscript`-handler ontvangt een `AbortSignal` dat wordt geactiveerd wanneer de gebruiker midden in een antwoord onderbreekt.

### Authenticatie uitschakelen

Standaard verifiëren zowel `attach()` als `SpeechEngineServer` de header `X-Elevenlabs-Speech-Engine-Authorization` bij elke binnenkomende verbinding. Als je server achter een infrastructuurlaag staat die binnenkomend verkeer al beperkt tot ElevenLabs (doorgaans een IP-allowlist voor [de egress-ranges van ElevenLabs](/docs/nl/eleven-api/resources/ip-allowlisting)), kun je JWT-verificatie overslaan door `disableAuth: true` door te geven:

```typescript
// Standalone — no apiKey required when disableAuth is true
new SpeechEngine.Server({ port: 3001, disableAuth: true, onTranscript }).start();

// Or on attach
elevenlabs.speechEngine.attach("seng_8k3m9xr4hjnfg983brhmhkd98n6", httpServer, "/ws", {
  disableAuth: true,
  onTranscript,
});
```

Wanneer authenticatie is uitgeschakeld, accepteert de server elke client die hem kan bereiken en geeft hij bij het opstarten een `console.warn` af.

> **Warning**
>
> Gebruik `disableAuth: true` alleen als je een IP-allowlist, aangepaste headerwaarden of een vergelijkbare
> beperking op netwerkniveau vóór de server hebt. Zonder zo'n beperking kan iedereen op internet een
> sessie openen en je rekenkracht en downstream LLM-quotum gebruiken.

## Events

Wanneer je `session.on()` rechtstreeks gebruikt in plaats van callbacks, zijn dit de eventnamen en de bijbehorende handlersignaturen.

| Event             | Handlersignatuur                                         |
| ----------------- | -------------------------------------------------------- |
| `user_transcript` | `(transcript: TranscriptMessage[], signal: AbortSignal)` |
| `init`            | `(conversationId: string)`                               |
| `close`           | `()`                                                     |
| `disconnected`    | `()`                                                     |
| `error`           | `(error: Error)`                                         |

Eventnaamconstanten zijn beschikbaar voor typeveilig gebruik:

```typescript
import { SpeechEngine } from "@elevenlabs/elevenlabs-js";

session.on(SpeechEngine.USER_TRANSCRIPT, (transcript, signal) => {
  /* ... */
});
```

## TranscriptMessage

Eén bericht in de gespreksgeschiedenis. Bij elke beurt wordt het volledige transcript doorgegeven aan `onTranscript`.

| Eigenschap | Type                  | Beschrijving                     |
| ---------- | --------------------- | -------------------------------- |
| `role`     | `"user"` \| `"agent"` | Wie het bericht heeft verstuurd. |
| `content`  | `string`              | De tekstinhoud van het bericht.  |

## Wire protocol

Ter referentie: dit zijn de JSON-berichten die via de WebSocket-verbinding worden uitgewisseld. De SDK handelt serialisatie en deserialisatie automatisch af.

### Binnenkomend (ElevenLabs API naar ontwikkelaarsserver)

| Berichttype       | Velden                                                     | Beschrijving                             |
| ----------------- | ---------------------------------------------------------- | ---------------------------------------- |
| `init`            | `conversation_id: string`                                  | Sessie geïnitialiseerd.                  |
| `user_transcript` | `user_transcript: TranscriptMessage[]`, `event_id: number` | Spraak van de gebruiker getranscribeerd. |
| `ping`            |                                                            | Keep-alive. SDK antwoordt met pong.      |
| `close`           |                                                            | Schone verbinding verbroken.             |
| `error`           | `message: string`                                          | Fout van de API.                         |

### Uitgaand (ontwikkelaarsserver naar ElevenLabs API)

| Berichttype      | Velden                                                     | Beschrijving                         |
| ---------------- | ---------------------------------------------------------- | ------------------------------------ |
| `agent_response` | `content: string`, `event_id: number`, `is_final: boolean` | LLM-antwoordchunk voor TTS-synthese. |
| `pong`           |                                                            | Antwoord op ping.                    |