Skip to content

voice-websocket/dist

Interfaces

AttachNodeVoiceWebSocketAdapterOptions

Properties

control?
optional control?: VoiceControlSurface;
initialGreeting?
optional initialGreeting?: string;
pathPrefix?
optional pathPrefix?: string;
profile?
optional profile?: VoiceProfile;
provider
provider: VoiceProvider;
reconnectGraceMs?
optional reconnectGraceMs?: number;
reconnectTokenTtlMs?
optional reconnectTokenTtlMs?: number;
recorder?
optional recorder?: VoiceRecorder;
runtime
runtime: VoiceRuntime;
server
server: Server;
store
store: VoiceSessionStore;
turnPreambleMs?
optional turnPreambleMs?: number;

HandleVoiceSocketOptions

Properties

connectionId
connectionId: string;
control?
optional control?: VoiceControlSurface;
initialGreeting?
optional initialGreeting?: string;
inputTranscriptDebounceMs?
optional inputTranscriptDebounceMs?: number;
profile?
optional profile?: VoiceProfile;
provider
provider: VoiceProvider;
reconnectGraceMs?
optional reconnectGraceMs?: number;
reconnectTokenTtlMs?
optional reconnectTokenTtlMs?: number;
recorder?
optional recorder?: VoiceRecorder;
runtime
runtime: VoiceRuntime;
signal?
optional signal?: AbortSignal;
socket
socket: VoiceSocketLike;
store
store: VoiceSessionStore;
token
token: string;
turnPreambleMs?
optional turnPreambleMs?: number;

InMemoryVoiceSessionStoreOptions

Properties

createToken?
optional createToken?: () => string;
Returns

string


VoiceControlNotification

Properties

createResponse?
optional createResponse?: boolean;
events?
optional events?: RuntimeEvent[];
message
message: string;
responseInstructions?
optional responseInstructions?: string;

VoiceControlSurface

Type Parameters

Type Parameter Default type
TArguments extends VoiceJsonValue VoiceJsonValue
TOutput extends VoiceJsonValue VoiceJsonValue

Properties

instructions?
optional instructions?: string;
tools
tools: VoiceControlTool<VoiceJsonObject>[];

Methods

createSessionInstructions()?
optional createSessionInstructions(input): string | Promise<string>;
Parameters
Parameter Type
input { session: VoiceSocketSession; }
input.session VoiceSocketSession
Returns

string | Promise\<string>

handleToolCall()
handleToolCall(input):
  | VoiceControlToolResult<TOutput>
| Promise<VoiceControlToolResult<TOutput>>;
Parameters
Parameter Type
input VoiceControlToolCall\<TArguments>
Returns

| VoiceControlToolResult\<TOutput> | Promise\<VoiceControlToolResult\<TOutput>>


VoiceControlTool

Type Parameters

Type Parameter Default type
TParameters extends VoiceJsonObject VoiceJsonObject

Properties

description?
optional description?: string;
name
name: string;
parameters?
optional parameters?: TParameters;

VoiceControlToolCall

Type Parameters

Type Parameter Default type
TArguments extends VoiceJsonValue VoiceJsonValue

Properties

arguments
arguments: TArguments;
callId
callId: string;
itemId?
optional itemId?: string;
name
name: string;
responseId?
optional responseId?: string;
session
session: VoiceSocketSession;
signal
signal: AbortSignal;

Methods

notify()?
optional notify(notification): Promise<void>;
Parameters
Parameter Type
notification VoiceControlNotification
Returns

Promise\<void>


VoiceControlToolResult

Type Parameters

Type Parameter Default type
TOutput extends VoiceJsonValue VoiceJsonValue

Properties

events?
optional events?: RuntimeEvent[];
output
output: TOutput;

VoiceJsonObject

Indexable

[key: string]: VoiceJsonValue

VoiceProvider

Properties

id
readonly id: string;

Methods

connect()
connect(input): Promise<VoiceProviderSession>;
Parameters
Parameter Type
input VoiceProviderConnectInput
Returns

Promise\<VoiceProviderSession>


VoiceProviderConnectInput

Properties

control?
optional control?: VoiceControlSurface;
profile?
optional profile?: VoiceProfile;
session
session: VoiceSocketSession;
signal
signal: AbortSignal;

Methods

onEvent()
onEvent(event): void | Promise<void>;
Parameters
Parameter Type
event VoiceProviderEvent
Returns

void | Promise\<void>


VoiceProviderSession

Methods

close()
close(): void | Promise<void>;
Returns

void | Promise\<void>

preamble()?
optional preamble(input): void | Promise<void>;
Parameters
Parameter Type
input { text: string; }
input.text string
Returns

void | Promise\<void>

send()
send(event): void | Promise<void>;
Parameters
Parameter Type
event VoiceBrowserClientEvent
Returns

void | Promise\<void>

speak()
speak(input): void | Promise<void>;
Parameters
Parameter Type
input { result?: HandleVoiceUserMessageResult; text: string; }
input.result? HandleVoiceUserMessageResult
input.text string
Returns

void | Promise\<void>


VoiceRecorder

Methods

onAudio()?
optional onAudio(input): void | Promise<void>;
Parameters
Parameter Type
input { audio: string; sequence?: number; session: VoiceSocketSession; speaker: "user" | "assistant"; }
input.audio string
input.sequence? number
input.session VoiceSocketSession
input.speaker "user" | "assistant"
Returns

void | Promise\<void>

onTranscript()?
optional onTranscript(input): void | Promise<void>;
Parameters
Parameter Type
input { runtimeEvent?: RuntimeEvent; session: VoiceSocketSession; speaker: "user" | "assistant"; text: string; }
input.runtimeEvent? RuntimeEvent
input.session VoiceSocketSession
input.speaker "user" | "assistant"
input.text string
Returns

void | Promise\<void>


VoiceRuntime

Methods

commitVoiceTranscript()?
optional commitVoiceTranscript(input): Promise<{
  event: RuntimeEvent;
  events: RuntimeEvent[];
  message: RuntimeEvent;
}>;
Parameters
Parameter Type
input { channelSegmentId: string; conversationId: string; endedAtMs?: number; metadata?: VoiceWebsocketProviderExtensionFields; recordingReferenceId?: string; speaker: "user" | "assistant"; startedAtMs?: number; text: string; transcriptionSource?: string; }
input.channelSegmentId string
input.conversationId string
input.endedAtMs? number
input.metadata? VoiceWebsocketProviderExtensionFields
input.recordingReferenceId? string
input.speaker "user" | "assistant"
input.startedAtMs? number
input.text string
input.transcriptionSource? string
Returns

Promise\<{ event: RuntimeEvent; events: RuntimeEvent[]; message: RuntimeEvent; }>

endVoiceSegment()
endVoiceSegment(input): Promise<RuntimeEvent>;
Parameters
Parameter Type
input { channelSegmentId: string; connectionId?: string; conversationId: string; reason?: string; }
input.channelSegmentId string
input.connectionId? string
input.conversationId string
input.reason? string
Returns

Promise\<RuntimeEvent>

handleVoiceUserMessage()
handleVoiceUserMessage<TTurn>(input): Promise<HandleVoiceUserMessageResult>;
Type Parameters
Type Parameter Default type
TTurn unknown
Parameters
Parameter Type
input HandleVoiceUserMessageInput\<TTurn>
Returns

Promise\<HandleVoiceUserMessageResult>

recordVoiceInterruption()
recordVoiceInterruption(input): Promise<RuntimeEvent>;
Parameters
Parameter Type
input { channelSegmentId: string; connectionId?: string; conversationId: string; interruptedMessageId?: string; offsetMs?: number; reason?: string; recordingReferenceId?: string; source?: "provider" | "userSpeech" | "adapter"; }
input.channelSegmentId string
input.connectionId? string
input.conversationId string
input.interruptedMessageId? string
input.offsetMs? number
input.reason? string
input.recordingReferenceId? string
input.source? "provider" | "userSpeech" | "adapter"
Returns

Promise\<RuntimeEvent>


VoiceSessionStore

Methods

acknowledgeAudio()
acknowledgeAudio(input): Promise<VoiceSocketSession>;
Parameters
Parameter Type
input { now?: Date; sequence: number; sessionId: string; }
input.now? Date
input.sequence number
input.sessionId string
Returns

Promise\<VoiceSocketSession>

claimToken()
claimToken(input): Promise<{
  reconnect: boolean;
  session: VoiceSocketSession;
  token: VoiceSocketToken;
}>;
Parameters
Parameter Type
input { connectionId: string; now?: Date; token: string; }
input.connectionId string
input.now? Date
input.token string
Returns

Promise\<{ reconnect: boolean; session: VoiceSocketSession; token: VoiceSocketToken; }>

createSession()
createSession(input): Promise<{
  session: VoiceSocketSession;
  socket: VoiceSocketMetadata;
}>;
Parameters
Parameter Type
input { now?: Date; result: StartVoiceResult; tokenTtlMs: number; }
input.now? Date
input.result StartVoiceResult
input.tokenTtlMs number
Returns

Promise\<{ session: VoiceSocketSession; socket: VoiceSocketMetadata; }>

getSession()
getSession(sessionId): Promise<VoiceSocketSession>;
Parameters
Parameter Type
sessionId string
Returns

Promise\<VoiceSocketSession>

issueReconnectToken()
issueReconnectToken(input): Promise<VoiceSocketToken>;
Parameters
Parameter Type
input { now?: Date; sessionId: string; ttlMs: number; }
input.now? Date
input.sessionId string
input.ttlMs number
Returns

Promise\<VoiceSocketToken>

markConnected()
markConnected(sessionId, now?): Promise<VoiceSocketSession>;
Parameters
Parameter Type
sessionId string
now? Date
Returns

Promise\<VoiceSocketSession>

markEnded()
markEnded(sessionId, now?): Promise<VoiceSocketSession>;
Parameters
Parameter Type
sessionId string
now? Date
Returns

Promise\<VoiceSocketSession>

markReconnecting()
markReconnecting(
   sessionId,
   now?,
graceMs?): Promise<VoiceSocketSession>;
Parameters
Parameter Type
sessionId string
now? Date
graceMs? number
Returns

Promise\<VoiceSocketSession>


VoiceSocketHandshakeOptions

Properties

baseUrl?
optional baseUrl?: string;
pathPrefix?
optional pathPrefix?: string;
store
store: VoiceSessionStore;
tokenTtlMs?
optional tokenTtlMs?: number;

VoiceSocketLike

Methods

close()
close(code?, reason?): void;
Parameters
Parameter Type
code? number
reason? string
Returns

void

on()
Call Signature
on(event, listener): void;
Parameters
Parameter Type
event "message"
listener (data) => void
Returns

void

Call Signature
on(event, listener): void;
Parameters
Parameter Type
event "close"
listener (code?, reason?) => void
Returns

void

Call Signature
on(event, listener): void;
Parameters
Parameter Type
event "error"
listener (error) => void
Returns

void

send()
send(data): void;
Parameters
Parameter Type
data string
Returns

void


VoiceSocketSession

Properties

channelSegment
channelSegment: VoiceChannelSegment;
connection
connection: VoiceConnection;
conversation
conversation: ConversationRecord<unknown>;
createdAt
createdAt: string;
events
events: RuntimeEvent[];
id
id: string;
lastAckSequence
lastAckSequence: number;
reconnectGraceUntil?
optional reconnectGraceUntil?: string;
status
status: "pending" | "connected" | "ended" | "reconnecting";
updatedAt
updatedAt: string;

VoiceSocketToken

Properties

connectionId
connectionId: string;
consumedAt?
optional consumedAt?: string;
expiresAt
expiresAt: string;
purpose
purpose: "start" | "reconnect";
sessionId
sessionId: string;
token
token: string;

VoiceWebsocketJsonObject

Extended by

Indexable

[key: string]: VoiceWebsocketProviderExtensionValue

VoiceWebsocketProviderExtensionFields

Extends

Indexable

[key: string]: VoiceWebsocketProviderExtensionValue

VoiceWebsocketProviderResponse

Extends

Indexable

[key: string]: VoiceWebsocketProviderExtensionValue

Type Aliases

VoiceBrowserClientEvent

type VoiceBrowserClientEvent =
  | {
  event_id?: string;
  session?: VoiceJsonObject;
  type: "session.update";
}
  | {
  audio: string;
  event_id?: string;
  sequence?: number;
  type: "input_audio_buffer.append";
}
  | {
  event_id?: string;
  type: "input_audio_buffer.commit";
}
  | {
  event_id?: string;
  type: "input_audio_buffer.clear";
}
  | {
  audioEndMs?: number;
  event_id?: string;
  interruptedMessageId?: string;
  playedUntilMs?: number;
  reason?: string;
  response_id?: string;
  type: "response.cancel";
}
  | {
  audio_end_ms?: number;
  content_index?: number;
  event_id?: string;
  item_id?: string;
  type: "conversation.item.truncate";
};

VoiceBrowserServerEvent

type VoiceBrowserServerEvent =
  | {
  channelSegment: StartVoiceResult["channelSegment"];
  connection: StartVoiceResult["connection"];
  conversation: StartVoiceResult["conversation"];
  event_id: string;
  lastAckSequence: number;
  protocol: VoiceProtocol;
  type: "cognidesk.connection.ready";
}
  | {
  event_id: string;
  expiresAt: string;
  token: string;
  type: "cognidesk.connection.reconnect_token";
}
  | {
  event_id: string;
  sequence: number;
  type: "cognidesk.audio.ack";
}
  | {
  event: RuntimeEvent;
  event_id: string;
  type: "cognidesk.runtime_event";
}
  | {
  activeJourneyId?: string;
  event_id: string;
  text: string;
  type: "cognidesk.turn.completed";
}
  | {
  event: RuntimeEvent;
  event_id: string;
  type: "cognidesk.interruption.recorded";
}
  | {
  elapsedMs: number;
  event_id: string;
  text: string;
  type: "cognidesk.voice.preamble";
}
  | {
  audio_start_ms?: number;
  event_id?: string;
  item_id?: string;
  type: "input_audio_buffer.speech_started";
}
  | {
  audio_end_ms?: number;
  event_id?: string;
  item_id?: string;
  type: "input_audio_buffer.speech_stopped";
}
  | {
  endedAtMs?: number;
  event_id: string;
  item_id?: string;
  metadata?: VoiceJsonObject;
  startedAtMs?: number;
  text: string;
  transcriptionSource?: string;
  type: "input_audio_transcription.completed";
}
  | {
  content_index?: number;
  delta: string;
  event_id?: string;
  item_id?: string;
  output_index?: number;
  response_id?: string;
  type: "response.output_audio.delta";
}
  | {
  content_index?: number;
  event_id?: string;
  item_id?: string;
  output_index?: number;
  response_id?: string;
  type: "response.output_audio.done";
}
  | {
  content_index?: number;
  delta: string;
  event_id?: string;
  item_id?: string;
  output_index?: number;
  response_id?: string;
  type: "response.output_audio_transcript.delta";
}
  | {
  content_index?: number;
  event_id?: string;
  item_id?: string;
  output_index?: number;
  response_id?: string;
  transcript: string;
  type: "response.output_audio_transcript.done";
}
  | {
  event_id?: string;
  response?: VoiceJsonObject;
  type: "response.done";
}
  | {
  error: {
     code: string;
     details?: VoiceJsonValue;
     message: string;
     retryable?: boolean;
  };
  event_id?: string;
  type: "error";
};

VoiceJsonPrimitive

type VoiceJsonPrimitive = string | number | boolean | null;

VoiceJsonValue

type VoiceJsonValue =
  | VoiceJsonPrimitive
  | VoiceJsonObject
  | VoiceJsonValue[];

VoiceProtocol

type VoiceProtocol = typeof COGNIDESK_VOICE_PROTOCOL;

VoiceProviderEvent

type VoiceProviderEvent =
  | {
  endedAtMs?: number;
  itemId?: string;
  kind: "input_transcript.completed";
  metadata?: VoiceJsonObject;
  startedAtMs?: number;
  text: string;
  transcriptionSource?: string;
}
  | {
  event: VoiceBrowserServerEvent;
  kind: "server_event";
}
  | {
  events: RuntimeEvent[];
  kind: "runtime_events";
}
  | {
  code?: string;
  details?: VoiceJsonValue;
  kind: "error";
  message: string;
  retryable?: boolean;
};

VoiceWebsocketJsonPrimitive

type VoiceWebsocketJsonPrimitive = string | number | boolean | null;

VoiceWebsocketJsonValue

type VoiceWebsocketJsonValue =
  | VoiceWebsocketJsonPrimitive
  | VoiceWebsocketJsonObject
  | readonly VoiceWebsocketJsonValue[];

VoiceWebsocketProviderExtensionValue

type VoiceWebsocketProviderExtensionValue =
  | VoiceWebsocketJsonValue
  | object
  | undefined;

VoiceWebsocketProviderPayload

type VoiceWebsocketProviderPayload = VoiceWebsocketJsonObject | object;

VoiceWebsocketProviderQuery

type VoiceWebsocketProviderQuery = Record<string, VoiceWebsocketProviderExtensionValue>;

Variables

COGNIDESK_VOICE_PROTOCOL

const COGNIDESK_VOICE_PROTOCOL: "cognidesk.voice.v1";

cognideskVoiceWebSocketProviderManifest

const cognideskVoiceWebSocketProviderManifest: {
  capabilities: {
     audiences?: ("customer-facing" | "internal-support" | "mixed")[];
     capability: string;
     changesWorkflow?: boolean;
     description?: string;
     exposesSensitiveData?: boolean;
     extension?: boolean;
     label?: string;
     metadata?: Record<string, unknown>;
     providerObjects?: {
        description?: string;
        kind: string;
        label?: string;
        metadata?: Record<string, unknown>;
        schemaName?: string;
     }[];
     requiresCredential?: boolean;
     sideEffect?: boolean;
  }[];
  category: string;
  channelAudiences: ("customer-facing" | "internal-support" | "mixed")[];
  coverage: {
     evidence: {
        label: string;
        url?: string;
     }[];
     notes: string[];
     scope:   | "support-workflow-subset"
        | "provider-api-subset"
        | "connector-required"
        | "local-protocol"
        | "full-provider-api";
  };
  credentialRequirements: {
     description?: string;
     id: string;
     label?: string;
     metadata?: Record<string, unknown>;
     required: boolean;
     scopes: string[];
  }[];
  directions: (
     | "receive-only"
     | "send-only"
     | "inbound-only"
     | "outbound-only"
    | "bidirectional")[];
  id: string;
  limitations: string[];
  maintainers: {
     name: string;
     type: "community" | "official" | "unknown" | "partner";
     url?: string;
  }[];
  metadata?: Record<string, unknown>;
  name: string;
  operations: {
     alias: string;
     audience?: "customer-facing" | "internal-support" | "mixed";
     audiences?: ("customer-facing" | "internal-support" | "mixed")[];
     capability: string;
     changesWorkflow?: boolean;
     description?: string;
     exposesSensitiveData?: boolean;
     extension: boolean;
     externallyVisible?: boolean;
     inputSchema?: unknown;
     inputSchemaName?: string;
     inputSchemaRef?: string;
     label?: string;
     metadata?: Record<string, unknown>;
     outputSchema?: unknown;
     outputSchemaName?: string;
     outputSchemaRef?: string;
     providerObject?: string;
     providerObjects?: {
        description?: string;
        kind: string;
        label?: string;
        metadata?: Record<string, unknown>;
        schemaName?: string;
     }[];
     providerOperation?: string;
     requiredPolicyIds?: string[];
     requiresApproval?: boolean;
     requiresCredential?: boolean;
     sideEffect?: boolean;
  }[];
  packageName: string;
  privacyNotes: string[];
  provider: string;
  trustLevel: "community" | "official" | "verified" | "experimental";
};

Type Declaration

Name Type
capabilities { audiences?: ("customer-facing" | "internal-support" | "mixed")[]; capability: string; changesWorkflow?: boolean; description?: string; exposesSensitiveData?: boolean; extension?: boolean; label?: string; metadata?: Record\<string, unknown>; providerObjects?: { description?: string; kind: string; label?: string; metadata?: Record\<string, unknown>; schemaName?: string; }[]; requiresCredential?: boolean; sideEffect?: boolean; }[]
category string
channelAudiences ("customer-facing" | "internal-support" | "mixed")[]
coverage { evidence: { label: string; url?: string; }[]; notes: string[]; scope: | "support-workflow-subset" | "provider-api-subset" | "connector-required" | "local-protocol" | "full-provider-api"; }
coverage.evidence { label: string; url?: string; }[]
coverage.notes string[]
coverage.scope | "support-workflow-subset" | "provider-api-subset" | "connector-required" | "local-protocol" | "full-provider-api"
credentialRequirements { description?: string; id: string; label?: string; metadata?: Record\<string, unknown>; required: boolean; scopes: string[]; }[]
directions ( | "receive-only" | "send-only" | "inbound-only" | "outbound-only" | "bidirectional")[]
id string
limitations string[]
maintainers { name: string; type: "community" | "official" | "unknown" | "partner"; url?: string; }[]
metadata? Record\<string, unknown>
name string
operations { alias: string; audience?: "customer-facing" | "internal-support" | "mixed"; audiences?: ("customer-facing" | "internal-support" | "mixed")[]; capability: string; changesWorkflow?: boolean; description?: string; exposesSensitiveData?: boolean; extension: boolean; externallyVisible?: boolean; inputSchema?: unknown; inputSchemaName?: string; inputSchemaRef?: string; label?: string; metadata?: Record\<string, unknown>; outputSchema?: unknown; outputSchemaName?: string; outputSchemaRef?: string; providerObject?: string; providerObjects?: { description?: string; kind: string; label?: string; metadata?: Record\<string, unknown>; schemaName?: string; }[]; providerOperation?: string; requiredPolicyIds?: string[]; requiresApproval?: boolean; requiresCredential?: boolean; sideEffect?: boolean; }[]
packageName string
privacyNotes string[]
provider string
trustLevel "community" | "official" | "verified" | "experimental"

Functions

attachNodeVoiceWebSocketAdapter()

function attachNodeVoiceWebSocketAdapter(options): {
  webSocketServer: Server<typeof WebSocket, typeof IncomingMessage>;
  close: void;
};

Parameters

Parameter Type
options AttachNodeVoiceWebSocketAdapterOptions

Returns

{
  webSocketServer: Server<typeof WebSocket, typeof IncomingMessage>;
  close: void;
}
Name Type
webSocketServer Server\<typeof WebSocket, typeof IncomingMessage>
close() () => void

createInMemoryVoiceSessionStore()

function createInMemoryVoiceSessionStore(options?): VoiceSessionStore;

Parameters

Parameter Type
options? InMemoryVoiceSessionStoreOptions

Returns

VoiceSessionStore


createVoiceSocketHandshake()

function createVoiceSocketHandshake(options): {
  createSocket: Promise<VoiceSocketMetadata>;
};

Parameters

Parameter Type
options VoiceSocketHandshakeOptions

Returns

{
  createSocket: Promise<VoiceSocketMetadata>;
}
Name Type
createSocket() (input) => Promise\<VoiceSocketMetadata>

handleVoiceSocket()

function handleVoiceSocket(options): Promise<void>;

Parameters

Parameter Type
options HandleVoiceSocketOptions

Returns

Promise\<void>