JavaScript SDK reference

This page documents the public API for the Speech Engine JavaScript SDK (@elevenlabs/elevenlabs-js).

Retrieve a SpeechEngineResource by its engine ID. The returned object provides methods to attach to an existing HTTP server, start a standalone server, or create individual sessions.

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

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

Attach to an existing Node.js HTTP server and begin accepting Speech Engine connections at the given path. Use this when you already have an HTTP server (e.g. Express, Fastify, or a plain http.createServer()) and want to add Speech Engine alongside your existing routes.

Handles WebSocket upgrades, path routing, and request verification automatically. Returns a SpeechEngineAttachment whose close() method stops accepting connections without affecting the HTTP server.

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

A shortcut is available directly on the client, combining get() and attach() into a single call:

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

Verify that an incoming request originates from the ElevenLabs Speech Engine API. Checks the X-Elevenlabs-Speech-Engine-Authorization header for a valid JWT signed with the SHA-256 hash of your API key.

Only needed when managing the WebSocket upgrade yourself. When using attach() or SpeechEngineServer, verification is handled automatically.

const isValid = await engine.verifyRequest(req);

Returns: Promise<boolean> — true if the request is valid.

Wrap an accepted WebSocket in a SpeechEngineSession. Use this for custom server integration or manual WebSocket handling.

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

Returns: SpeechEngineSession

A standalone WebSocket server that accepts Speech Engine connections without requiring an existing HTTP server. Use this when your server's only purpose is handling Speech Engine connections.

For integration with an existing HTTP server (e.g. Express, Fastify), use engine.attach() instead.

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

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

server.start();

Start the standalone WebSocket server on the configured port. Verifies each incoming connection against the ElevenLabs API using the configured API key, unless disableAuth: true was set.

server.start();

Stop the WebSocket server and close all active connections.

await server.stop();

Wrap an existing WebSocket in a SpeechEngineSession with the server's callbacks wired up. Use this when you manage your own WebSocket server and want to wrap individual connections.

const session = server.handleConnection(ws);

Returns: SpeechEngineSession

Wraps a single WebSocket connection. Each connection represents one conversation. The session emits events for transcripts and lifecycle changes, and provides methods to send LLM responses back.

When a new transcript arrives, the previous transcript handler's abort signal is fired, interrupting any in-flight LLM call.

Register a handler for an event. Returns the session for chaining.

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

Remove a previously registered handler.

session.off("user_transcript", listener);

Register a handler that fires once then removes itself.

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

Send an LLM response back to the Speech Engine API for text-to-speech synthesis. Must be called inside an onTranscript handler. Calling it outside of a handler emits a warning and returns without sending.

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

The SDK auto-detects and extracts text from the following LLM stream formats:

Close the session and the underlying WebSocket connection.

session.close();

Returned by engine.attach(). Controls the lifecycle of the WebSocket server without affecting the HTTP server it was attached to.

Stop accepting new connections, remove the upgrade listener from the HTTP server, and close the underlying WebSocket server.

await attachment.close();

The callback object passed to attach() or SpeechEngineServer. All callbacks are optional.

The onTranscript handler receives an AbortSignal that fires when the user interrupts mid-response.

By default both attach() and SpeechEngineServer verify the X-Elevenlabs-Speech-Engine-Authorization header on every incoming connection. If your server sits behind an infrastructure layer that already restricts incoming traffic to ElevenLabs (typically an IP allowlist scoped to ElevenLabs' egress ranges), you can skip JWT verification by passing disableAuth: true:

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

When auth is disabled the server accepts any client that can reach it and emits a console.warn on startup.

When using session.on() directly instead of callbacks, these are the event names and their handler signatures.

Event name constants are available for type-safe usage:

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

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

A single message in the conversation history. The full transcript is passed to onTranscript on every turn.

For reference, these are the JSON messages exchanged over the WebSocket connection. The SDK handles serialization and deserialization automatically.