Skip to content

CloudflareRealtimeTransportLayer

An adapter transport for Cloudflare Workers (workerd) environments.

Cloudflare Workers cannot open outbound client WebSockets using the global WebSocket constructor. Instead, a fetch() request with Upgrade: websocket must be performed and the returned response.webSocket must be accept()ed. This transport encapsulates that pattern and plugs into the Realtime SDK via the factory-based createWebSocket option.

It behaves like OpenAIRealtimeWebSocket, but establishes the connection using fetch() and sets skipOpenEventListeners: true since workerd sockets do not emit a traditional open event after acceptance.

Reference: Response API — response.webSocket (Cloudflare Workers). https://developers.cloudflare.com/workers/runtime-apis/response/.

  • OpenAIRealtimeWebSocket
  • RealtimeTransportLayer
new CloudflareRealtimeTransportLayer(options): CloudflareRealtimeTransportLayer;
Parameter Type

options

OpenAIRealtimeWebSocketOptions

CloudflareRealtimeTransportLayer

OpenAIRealtimeWebSocket.constructor
set _tracingConfig(tracingConfig): void;

Sets the internal tracing config. This is used to track the tracing config that has been set during the session.create event.

Parameter Type

tracingConfig

null | RealtimeTracingConfig

void

OpenAIRealtimeWebSocket._tracingConfig

get connectionState(): WebSocketState;

The current connection state of the WebSocket connection.

WebSocketState

OpenAIRealtimeWebSocket.connectionState

get currentModel(): OpenAIRealtimeModels;

The current model that is being used by the transport layer.

OpenAIRealtimeModels

set currentModel(model): void;

The current model that is being used by the transport layer. Note: The model cannot be changed mid conversation.

Parameter Type

model

OpenAIRealtimeModels

void

OpenAIRealtimeWebSocket.currentModel

get muted(): null;

Always returns null as the WebSocket transport layer does not handle muting. Instead, this should be handled by the client by not triggering the sendAudio method.

null

RealtimeTransportLayer.muted
OpenAIRealtimeWebSocket.muted

get status(): "connected" | "disconnected" | "connecting";

The current status of the WebSocket connection.

"connected" | "disconnected" | "connecting"

RealtimeTransportLayer.status

TwilioRealtimeTransportLayer.status

_cancelResponse(): void;

Send a cancel response event to the Realtime API. This is used to cancel an ongoing response that the model is currently generating.

void

OpenAIRealtimeWebSocket._cancelResponse

_interrupt(elapsedTime, cancelOngoingResponse?): void;

Do NOT call this method directly. Call interrupt() instead for proper interruption handling.

This method is used to send the right events to the API to inform the model that the user has interrupted the response. It might be overridden/extended by an extended transport layer. See the TwilioRealtimeTransportLayer for an example.

Parameter Type Description

elapsedTime

number

The elapsed time since the response started.

cancelOngoingResponse?

boolean

void

OpenAIRealtimeWebSocket._interrupt

addImage(image, options?): void;

Sends an image to the model

Parameter Type Description

image

string

The image to send

options?

{ triggerResponse?: boolean; }

Additional options

options.triggerResponse?

boolean

Whether to trigger a response from the model

void

RealtimeTransportLayer.addImage
OpenAIRealtimeWebSocket.addImage

close(): void;

Close the WebSocket connection.

This will also reset any internal connection tracking used for interruption handling.

void

RealtimeTransportLayer.close
OpenAIRealtimeWebSocket.close

connect(options): Promise<void>;
Parameter Type

options

RealtimeTransportLayerConnectOptions

Promise<void>

RealtimeTransportLayer.connect
OpenAIRealtimeWebSocket.connect

emit<K>(type, ...args): boolean;
Type Parameter

K extends keyof RealtimeTransportEventTypes

Parameter Type

type

K

args

OpenAIRealtimeEventTypes[K]

boolean

RealtimeTransportLayer.emit
OpenAIRealtimeWebSocket.emit

interrupt(cancelOngoingResponse?): void;

Interrupt the ongoing response. This method is triggered automatically by the client when voice activity detection (VAD) is enabled (default) as well as when an output guardrail got triggered.

You can also call this method directly if you want to interrupt the conversation for example based on an event in the client.

Parameter Type

cancelOngoingResponse?

boolean

void

RealtimeTransportLayer.interrupt
OpenAIRealtimeWebSocket.interrupt

mute(_muted): never;

Will throw an error as the WebSocket transport layer does not support muting.

Parameter Type

_muted

boolean

never

RealtimeTransportLayer.mute
OpenAIRealtimeWebSocket.mute

off<K>(type, listener): EventEmitter<EventTypes>;
Type Parameter

K extends keyof RealtimeTransportEventTypes

Parameter Type

type

K

listener

(…args) => void

EventEmitter<EventTypes>

RealtimeTransportLayer.off
OpenAIRealtimeWebSocket.off

on<K>(type, listener): EventEmitter<EventTypes>;
Type Parameter

K extends keyof RealtimeTransportEventTypes

Parameter Type

type

K

listener

(…args) => void

EventEmitter<EventTypes>

RealtimeTransportLayer.on
OpenAIRealtimeWebSocket.on

once<K>(type, listener): EventEmitter<EventTypes>;
Type Parameter

K extends keyof RealtimeTransportEventTypes

Parameter Type

type

K

listener

(…args) => void

EventEmitter<EventTypes>

RealtimeTransportLayer.once
OpenAIRealtimeWebSocket.once

resetHistory(oldHistory, newHistory): void;

Reset the history of the conversation. This will create a diff between the old and new history and send the necessary events to the Realtime API to update the history.

Parameter Type Description

oldHistory

RealtimeItem[]

The old history of the conversation.

newHistory

RealtimeItem[]

The new history of the conversation.

void

RealtimeTransportLayer.resetHistory
OpenAIRealtimeWebSocket.resetHistory

sendAudio(audio, options?): void;

Send an audio buffer to the Realtime API. This is used for your client to send audio to the model to respond.

Parameter Type Description

audio

ArrayBuffer

The audio buffer to send.

options?

{ commit?: boolean; }

The options for the audio buffer.

options.commit?

boolean

void

RealtimeTransportLayer.sendAudio
OpenAIRealtimeWebSocket.sendAudio

sendEvent(event): void;

Send an event to the Realtime API. This will stringify the event and send it directly to the API. This can be used if you want to take control over the connection and send events manually.

Parameter Type Description

event

RealtimeClientMessage

The event to send.

void

RealtimeTransportLayer.sendEvent
OpenAIRealtimeWebSocket.sendEvent

sendFunctionCallOutput(
toolCall,
output,
startResponse?): void;

Send the output of a function call to the Realtime API.

Parameter Type Description

toolCall

TransportToolCallEvent

The tool call to send the output for.

output

string

The output of the function call.

startResponse?

boolean

Whether to start a new response after sending the output.

void

RealtimeTransportLayer.sendFunctionCallOutput
OpenAIRealtimeWebSocket.sendFunctionCallOutput

sendMcpResponse(approvalRequest, approved): void;

Sends a response for an MCP tool call

Parameter Type Description

approvalRequest

{ approved?: null | boolean; arguments: Record<string, any>; itemId: string; name: string; serverLabel: string; type: "mcp_approval_request"; }

The approval request to respond to

approvalRequest.approved?

null | boolean

approvalRequest.arguments

Record<string, any>

approvalRequest.itemId

string

approvalRequest.name

string

approvalRequest.serverLabel

string

approvalRequest.type

"mcp_approval_request"

approved

boolean

Whether the tool call was approved or rejected

void

RealtimeTransportLayer.sendMcpResponse
OpenAIRealtimeWebSocket.sendMcpResponse

sendMessage(
message,
otherEventData,
__namedParameters?): void;

Send a message to the Realtime API. This will create a new item in the conversation and trigger a response.

Parameter Type Description

message

RealtimeUserInput

The message to send.

otherEventData

Record<string, any>

Additional event data to send.

__namedParameters?

{ triggerResponse?: boolean; }

__namedParameters.triggerResponse?

boolean

void

RealtimeTransportLayer.sendMessage
OpenAIRealtimeWebSocket.sendMessage

updateSessionConfig(config): void;

Updates the session config. This will merge it with the current session config with the default values and send it to the Realtime API.

Parameter Type Description

config

Partial<RealtimeSessionConfig>

The session config to update.

void

RealtimeTransportLayer.updateSessionConfig
OpenAIRealtimeWebSocket.updateSessionConfig