Implementation:Openai Openai node Stable RealtimeBase

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

Overview

The internal-base module provides the abstract OpenAIRealtimeEmitter base class and utility functions that underpin both the stable WebSocket and Node.js realtime client implementations.

Description

This module defines three key exports: the OpenAIRealtimeError error class, the abstract OpenAIRealtimeEmitter base class, and the buildRealtimeURL utility function.

OpenAIRealtimeError extends OpenAIError and wraps error data from the API's realtime error events, preserving the error payload and event_id from the server. The abstract OpenAIRealtimeEmitter extends EventEmitter with a strongly-typed event map (RealtimeEvents) that includes a generic event handler for all server events, an error handler for error events, and individual handlers for each specific server event type. It declares abstract send and close methods that concrete subclasses (WebSocket and WS implementations) must implement.

The _onError protected method provides centralized error handling logic: if no error listener is bound, it creates an unhandled rejection with a helpful message guiding developers to add an error handler; otherwise, it emits the error to registered listeners. The buildRealtimeURL function constructs a wss:// URL from the client's base URL, appending the model as a query parameter (or for Azure, the deployment name and API version). The isAzure helper determines whether the client is an Azure instance for protocol differences.

Usage

This module is not used directly by end users. It is an internal foundation for the OpenAIRealtimeWebSocket (browser) and OpenAIRealtimeWS (Node.js) classes. Understanding it is valuable when extending the realtime client or debugging connection-level issues.

Code Reference

Source Location

• Repository: openai-node
• File: src/realtime/internal-base.ts

Signature

export class OpenAIRealtimeError extends OpenAIError {
  error?: RealtimeError | undefined;
  event_id?: string | undefined;
  constructor(message: string, event: RealtimeErrorEvent | null);
}

export abstract class OpenAIRealtimeEmitter extends EventEmitter<RealtimeEvents> {
  abstract send(event: RealtimeClientEvent): void;
  abstract close(props?: { code: number; reason: string }): void;
  protected _onError(event: RealtimeErrorEvent | null, message?: string, cause?: any): void;
}

export function isAzure(client: Pick<OpenAI, 'apiKey' | 'baseURL'>): client is AzureOpenAI;

export function buildRealtimeURL(client: Pick<OpenAI, 'apiKey' | 'baseURL'>, model: string): URL;

Import

import OpenAI from 'openai';

I/O Contract

Inputs

Name	Type	Required	Description
event	RealtimeClientEvent	Yes (send)	The client event to send to the Realtime API.
props.code	number	No (close)	WebSocket close code.
props.reason	string	No (close)	WebSocket close reason.
client	'baseURL'>	Yes (buildRealtimeURL)	Client instance for URL construction.
model	string	Yes (buildRealtimeURL)	The realtime model name for the URL query parameter.

Outputs

Name	Type	Description
URL	URL	(buildRealtimeURL) A wss:// URL configured for the realtime API.
event callbacks	RealtimeServerEvent	Typed event emissions for all server event types.
error callbacks	OpenAIRealtimeError	Error events with API error data and event IDs.

Usage Examples

// This module is internal; it is used by the concrete realtime client classes.
// The following demonstrates the pattern used by subclasses:

import OpenAI from 'openai';

const client = new OpenAI();

// Using the WebSocket implementation (which extends OpenAIRealtimeEmitter)
const rt = new OpenAI.RealtimeWebSocket({ model: 'gpt-realtime' }, client);

// The emitter pattern from the base class
rt.on('event', (event) => {
  console.log('Received:', event.type);
});

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

// send() and close() are provided by the concrete subclass
rt.send({ type: 'input_audio_buffer.clear' });
rt.close();

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime