OpenAI

API clients for OpenAI chat completions, responses, and real-time voice scenarios.

View as Markdown

OpenAI provides VoxEngine clients for chat completions, the Responses API, and the Realtime API. Use this page as the consolidated API surface for creating clients, configuring parameters, sending media, and handling provider events.

For real-time voice scenarios, create an OpenAI.RealtimeAPIClient, bridge call media to it, and listen for OpenAI.Events plus OpenAI.RealtimeAPIEvents.

Contents

  • Usage: required module import and high-level client flow.
  • Factory functions: create chat completions, responses, or realtime clients.
  • Parameter types: configuration objects used by OpenAI client factories.
  • Client methods: methods grouped by client type.
  • Events: WebSocket media bridge events.
  • RealtimeAPIEvents: OpenAI Realtime server events and provider payload fields.

Usage

Add the module before using the namespace:

1require(Modules.OpenAI);

Create the client for the API style you need, then call methods on that client instance. Realtime voice scenarios typically use createRealtimeAPIClient, sendMediaTo, and event listeners for Realtime API server messages.

Factory functions

Use the tabs to choose the OpenAI API surface you are creating: Chat Completions for text chat completions, Responses for the newer Responses API, or Realtime for voice scenarios over WebSocket.

Creates a client for the Chat Completions API.

createChatCompletionsAPIClient

Creates a new OpenAI.ChatCompletionsAPIClient instance.

1createChatCompletionsAPIClient(parameters: {
2 statistics?: boolean;
3 trace?: boolean;
4 privacy?: boolean;
5 apiKey: string;
6 storeContext?: boolean;
7 baseUrl?: string;
8 project?: string;
9 summaryModel?: string;
10 summaryPrompt?: string;
11}): Promise<OpenAI.ChatCompletionsAPIClient>

The required parameters object is typed as OpenAI.ChatCompletionsAPIClientParameters.

Parameters

ParameterTypeReq.Description
parametersChatCompletionsAPIClientParametersOpenAI.ChatCompletionsAPIClient parameters. Can be passed as arguments to the OpenAI.createChatCompletionsAPIClient method.
statisticsbooleanEnables statistics functionality.
tracebooleanWhether to enable the tracing functionality. If tracing is enabled, a URL to the trace file appears in the ‘websocket.created’ message. The file contains all sent and received WebSocket messages in the plain text format. The file is uploaded to the S3 storage. NOTE: enable this only for diagnostic purposes. You can provide the trace file to our support team to help investigating issues.
privacybooleanWhether to enable the privacy functionality. If privacy is enabled, the logging for the WebSocket connection is disabled. NOTE: the default value is false.
apiKeystringAPI key for the OpenAI API.
storeContextbooleanWhether to store the context in the client. The default value is false.
baseUrlstringBase URL for the OpenAI API.
projectstringProject for the OpenAI API.
summaryModelstringModel for the summary generation. The default value is gpt-4o.
summaryPromptstringPrompt for the summary generation. If not specified, the default prompt is used. The API Client automatically inserts the previous summary here. The default prompt is: You are maintaining a running summary of an ongoing conversation. Below is: 1. The previous summary 2. The messages between user and assistant you need to summarize Provide a summary to reflect the information. ### Instructions: - Preserve important existing context from the previous summary - Integrate new key information, decisions, and developments - Remove outdated or redundant details - Avoid repeating unchanged information - Keep the summary concise and context-efficient - Maintain a neutral and factual tone

Returns

TypeDescription
Promise<OpenAI.ChatCompletionsAPIClient>Resolves to the OpenAI.ChatCompletionsAPIClient instance.

Parameter types

These parameter objects match the same three API families as the factory functions.

OpenAI.ChatCompletionsAPIClient parameters. Can be passed as arguments to the OpenAI.createChatCompletionsAPIClient method.

PropertyTypeReq.Description
apiKeystringAPI key for the OpenAI API.
baseUrlstringBase URL for the OpenAI API.
privacyboolean_inherited from WebSocketBasedClientParameters Whether to enable the privacy functionality. If privacy is enabled, the logging for the WebSocket connection is disabled. NOTE: the default value is false.
projectstringProject for the OpenAI API.
statisticsboolean_inherited from WebSocketBasedClientParameters Enables statistics functionality.
storeContextbooleanWhether to store the context in the client. The default value is false.
summaryModelstringModel for the summary generation. The default value is gpt-4o.
summaryPromptstringPrompt for the summary generation. If not specified, the default prompt is used. The API Client automatically inserts the previous summary here. The default prompt is: You are maintaining a running summary of an ongoing conversation. Below is: 1. The previous summary 2. The messages between user and assistant you need to summarize Provide a summary to reflect the information. ### Instructions: - Preserve important existing context from the previous summary - Integrate new key information, decisions, and developments - Remove outdated or redundant details - Avoid repeating unchanged information - Keep the summary concise and context-efficient - Maintain a neutral and factual tone
traceboolean_inherited from WebSocketBasedClientParameters Whether to enable the tracing functionality. If tracing is enabled, a URL to the trace file appears in the ‘websocket.created’ message. The file contains all sent and received WebSocket messages in the plain text format. The file is uploaded to the S3 storage. NOTE: enable this only for diagnostic purposes. You can provide the trace file to our support team to help investigating issues.

Client methods

Use the tabs to switch between Chat Completions, Responses, and Realtime client methods.

addEventListener

Adds a handler for the specified OpenAI.ChatCompletionsAPIEvents or OpenAI.Events event. Use only functions as handlers; anything except a function leads to the error and scenario termination when a handler is called.

1addEventListener(event: OpenAI.Events | OpenAI.ChatCompletionsAPIEvents | string, callback: (event: object) => any): void

Parameters

ParameterTypeReq.Description
eventOpenAI.Events | OpenAI.ChatCompletionsAPIEvents | stringEvent constant or event name to subscribe to.
callback(event: object) => anyFunction called when the event is emitted.

Returns

TypeDescription
voidDoes not return a value.

close

Closes the OpenAI connection (over WebSocket) or connection attempt.

1close(): void

Parameters

This method does not accept parameters.

Returns

TypeDescription
voidDoes not return a value.

createChatCompletions

Creates a model response for the given chat conversation. https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create

1createChatCompletions(parameters: Object): void

Parameters

ParameterTypeReq.Description
parametersObject

Returns

TypeDescription
voidDoes not return a value.

id

Returns the ChatCompletionsAPIClient id.

1id(): string

Parameters

This method does not accept parameters.

Returns

TypeDescription
stringThe requested string value.

removeEventListener

Removes a handler for the specified OpenAI.ChatCompletionsAPIEvents or OpenAI.Events event.

1removeEventListener(event: OpenAI.Events | OpenAI.ChatCompletionsAPIEvents | string, callback?: (event: object) => any): void

Parameters

ParameterTypeReq.Description
eventOpenAI.Events | OpenAI.ChatCompletionsAPIEvents | stringEvent constant or event name to subscribe to.
callback(event: object) => anyFunction called when the event is emitted.

Returns

TypeDescription
voidDoes not return a value.

webSocketId

Returns the OpenAI WebSocket id.

1webSocketId(): string

Parameters

This method does not accept parameters.

Returns

TypeDescription
stringThe requested string value.

Events

Event tabs mirror the same API families: media bridge events apply to realtime WebSocket media, while the API-specific tabs document provider responses for each client type.

Media bridge events

These events describe audio received through the OpenAI WebSocket media bridge.

WebSocketMediaStarted

Triggered when the audio stream sent by a third party through an OpenAI WebSocket is started playing.

Event constant: Events.WebSocketMediaStarted

Payload

FieldTypeReq.Description
clientRealtimeAPIClient | ResponsesAPIClient | ChatCompletionsAPIClientThe OpenAI.RealtimeAPIClient or OpenAI.ResponsesAPIClient | OpenAI.ChatCompletionsAPIClient instance.
tagstringSpecial tag to name audio streams sent over one WebSocket connection. With it, one can send 2 audios to 2 different media units at the same time.
encodingstringAudio encoding formats.
customParameters{ [key: string]: string }Custom parameters.

WebSocketMediaEnded

Triggers after the end of the audio stream sent by a third party through an OpenAI WebSocket (1 second of silence).

Event constant: Events.WebSocketMediaEnded

Payload

FieldTypeReq.Description
clientRealtimeAPIClient | ResponsesAPIClient | ChatCompletionsAPIClientThe OpenAI.RealtimeAPIClient or OpenAI.ResponsesAPIClient | OpenAI.ChatCompletionsAPIClient instance.
tagstringSpecial tag to name audio streams sent over one WebSocket connection. With it, one can send 2 audios to 2 different media units at the same time.
mediaInfoWebSocketMediaInfoInformation about the audio stream that can be obtained after the stream stops or pauses (1 second of silence).