Implementation:Openai Openai node Beta RealtimeWS

Knowledge Sources	Openai_Openai_node
Domains	SDK, Realtime, WebSocket
Last Updated	2026-02-15 12:00 GMT

Overview

OpenAIRealtimeWS is the Node.js beta realtime client that uses the ws library to connect to the OpenAI Realtime API.

Description

OpenAIRealtimeWS extends OpenAIRealtimeEmitter to provide a server-side realtime client backed by the ws (WebSocket) npm package. Unlike the browser-based OpenAIRealtimeWebSocket, this class authenticates using HTTP headers -- specifically the Authorization: Bearer {apiKey} header and the OpenAI-Beta: realtime=v1 header -- which is more secure than sub-protocol-based authentication.

The constructor accepts a model string and optional ws.ClientOptions for advanced socket configuration (custom headers, TLS settings, etc.). It builds the connection URL using the shared buildRealtimeURL utility, then opens a WS.WebSocket connection with merged headers. Incoming messages are parsed as JSON and emitted as strongly-typed events; socket-level errors are routed through the inherited _onError handler.

The class provides two static factory methods: create() for standard OpenAI connections with function-based API key resolution, and azure() for Azure OpenAI deployments which handles Azure-specific authentication (adding api-key headers) and deployment name lookup. Both factories are async to allow pre-resolving dynamic API keys before the socket is opened.

Usage

Use OpenAIRealtimeWS in Node.js server environments where the ws package is available. This is the preferred choice for backend applications, CLI tools, and server-side integrations with the OpenAI Realtime API. For browser environments, use OpenAIRealtimeWebSocket instead.

Code Reference

Source Location

• Repository: openai-node
• File: src/beta/realtime/ws.ts

Signature

export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
  url: URL;
  socket: WS.WebSocket;

  constructor(
    props: {
      model: string;
      options?: WS.ClientOptions | undefined;
    },
    client?: Pick<OpenAI, 'apiKey' | 'baseURL'>,
  );

  static async create(
    client: Pick<OpenAI, 'apiKey' | 'baseURL' | '_callApiKey'>,
    props: { model: string; options?: WS.ClientOptions | undefined },
  ): Promise<OpenAIRealtimeWS>;

  static async azure(
    client: Pick<AzureOpenAI, '_callApiKey' | 'apiVersion' | 'apiKey' | 'baseURL' | 'deploymentName'>,
    props?: { deploymentName?: string; options?: WS.ClientOptions | undefined },
  ): Promise<OpenAIRealtimeWS>;

  send(event: RealtimeClientEvent): void;
  close(props?: { code: number; reason: string }): void;
}

Import

import { OpenAIRealtimeWS } from 'openai/beta/realtime/ws';

I/O Contract

Inputs

Name	Type	Required	Description
model	string	Yes	The model identifier for the realtime session (e.g. "gpt-4o-realtime-preview").
options	WS.ClientOptions	No	Additional ws library options such as custom headers, TLS settings, or agent configuration.
client	'baseURL'>	No	An existing OpenAI or AzureOpenAI client instance. A new OpenAI client is created if not provided.

Outputs

Name	Type	Description
(instance)	OpenAIRealtimeWS	A connected realtime client with event emitter interface.
url	URL	The WSS URL used for the connection.
socket	WS.WebSocket	The underlying ws library WebSocket instance.

Usage Examples

import { OpenAIRealtimeWS } from 'openai/beta/realtime/ws';
import OpenAI from 'openai';

// Basic Node.js usage
const rt = new OpenAIRealtimeWS({ model: 'gpt-4o-realtime-preview' });

rt.on('session.created', (event) => {
  console.log('Realtime session created:', event.session.id);
  rt.send({ type: 'response.create' });
});

rt.on('error', (error) => {
  console.error('Realtime error:', error.message);
});

// Using static create() with an existing client
const client = new OpenAI();
const rt2 = await OpenAIRealtimeWS.create(client, {
  model: 'gpt-4o-realtime-preview',
});

// Azure usage
import { AzureOpenAI } from 'openai';
const azureClient = new AzureOpenAI({
  endpoint: 'https://my-resource.openai.azure.com/',
  apiVersion: '2024-06-01',
  apiKey: 'my-azure-key',
});
const rt3 = await OpenAIRealtimeWS.azure(azureClient, {
  deploymentName: 'my-realtime-deployment',
});

// Close connection
rt.close({ code: 1000, reason: 'Done' });

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime