Environment:Openai Openai node WebSocket Dependency
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Realtime |
| Last Updated | 2026-02-15 12:00 GMT |
Overview
Optional `ws` WebSocket library required for Node.js Realtime API connections via `OpenAIRealtimeWS`.
Description
The OpenAI Node.js SDK provides two Realtime API client classes: `OpenAIRealtimeWS` (uses the `ws` npm package for Node.js) and `OpenAIRealtimeWebSocket` (uses the browser-native `WebSocket` global). The `ws` package is declared as an optional peer dependency (`^8.18.0`). It is only needed when using `OpenAIRealtimeWS` in a Node.js environment. Browser, Deno, Bun, and Edge Runtime environments should use `OpenAIRealtimeWebSocket` instead, which requires no additional dependency.
Usage
Use this environment when building Realtime API applications that run in Node.js and use `OpenAIRealtimeWS`. This is the prerequisite for the Realtime Conversation workflow in server-side Node.js applications.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Runtime | Node.js >= 20 LTS | `ws` is a Node.js-specific WebSocket library |
| Network | WebSocket outbound to `wss://api.openai.com` | Realtime API uses persistent WebSocket connections |
Dependencies
System Packages
- None
NPM Packages
- `ws` >= 8.18.0 (optional peer dependency)
- `@types/ws` >= 8.5.13 (TypeScript type definitions, dev only)
Credentials
No additional credentials beyond those in the Environment:Openai_Openai_node_OpenAI_API_Credentials environment.
Quick Install
# Install ws for Node.js Realtime API support
npm install ws
Code Evidence
Direct import of `ws` in `src/realtime/ws.ts:1`:
import * as WS from 'ws';
Peer dependency declaration in `package.json:79-89`:
"peerDependencies": {
"ws": "^8.18.0",
"zod": "^3.25 || ^4.0"
},
"peerDependenciesMeta": {
"ws": {
"optional": true
},
"zod": {
"optional": true
}
}
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Cannot find module 'ws'` | `ws` not installed when using `OpenAIRealtimeWS` | Run `npm install ws` |
| `could not parse websocket event` | Malformed JSON from WebSocket | Check network connectivity; SDK handles gracefully with error event |
| `could not send data` | WebSocket connection dropped | Reconnect; implement error handler via `rt.on('error', ...)` |
Compatibility Notes
- Browser / Edge Runtime: Use `OpenAIRealtimeWebSocket` instead, which uses the global `WebSocket` API and does not require `ws`.
- Deno: Has built-in WebSocket support; use `OpenAIRealtimeWebSocket`.
- Bun: Has built-in WebSocket support; use `OpenAIRealtimeWebSocket`.
- Ephemeral Tokens: In browser environments, create ephemeral session tokens server-side to avoid exposing API keys.