Cartesia | Voximplant Voice AI

Cartesia provides a VoxEngine client for connecting a call or media unit to the Cartesia Agents WebSocket API.

Use Cartesia.createAgentsClient(...) to create an AgentsClient for the current scenario.

Learn how Cartesia Line fits into a VoxEngine call flow.

Usage: required module import and basic flow.
Factory functions: create the Cartesia Agents client.
Methods: start, DTMF, and custom agent messages.
Events: WebSocket media bridge events.
AgentsEvents: Cartesia Agents event names and payload fields.

Usage

Add the module before using the namespace:

require(Modules.Cartesia);

Create the client, bridge media, and listen for Cartesia Agents events.

Factory functions

createAgentsClient

Creates a Cartesia.AgentsClient instance.

createAgentsClient(parameters: AgentsClientParameters): Promise<Cartesia.AgentsClient>

Parameters

Parameter	Type	Req.	Description
`parameters`	`AgentsClientParameters`	✓

Returns

Type	Description
`Promise<Cartesia.AgentsClient>`	Resolves to the `Cartesia.AgentsClient` instance.

createRealtimeTTSPlayer

Creates a new Cartesia.RealtimeTTSPlayer instance with the specified text (TTS is used to play the text). You can attach media streams later via the Cartesia.RealtimeTTSPlayer.sendMediaTo or VoxEngine.sendMediaBetween methods.

createRealtimeTTSPlayer(text: string, parameters?: RealtimeTTSPlayerParameters): RealtimeTTSPlayer

Parameters

Parameter	Type	Req.	Description
`text`	`string`	✓
`parameters`	`RealtimeTTSPlayerParameters`	✗

Returns

Type	Description
`RealtimeTTSPlayer`	The requested `RealtimeTTSPlayer` value.

AgentsClient

Methods

addEventListener

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

addEventListener(event: Cartesia.Events | Cartesia.AgentsEvents | string, callback: (event: object) => any): void

Parameters

Parameter	Type	Req.	Description
`event`	`Cartesia.Events \| Cartesia.AgentsEvents \| string`	✓	Event constant or event name to subscribe to.
`callback`	`(event: object) => any`	✓	Function called when the event is emitted.

Returns

Type	Description
`void`	Does not return a value.

clearMediaBuffer

Clears the Cartesia WebSocket media buffer.

clearMediaBuffer(parameters?: ClearMediaBufferParameters): void

Parameters

Parameter	Type	Req.	Description
`parameters`	`ClearMediaBufferParameters`	✗

Returns

Type	Description
`void`	Does not return a value.

close

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

close(): void

Parameters

This method does not accept parameters.

Returns

Type	Description
`void`	Does not return a value.

custom

Sends custom metadata to the agent. https://docs.cartesia.ai/line/integrations/websocket-api#custom-event

custom(parameters: Object): void

Parameters

Parameter	Type	Req.	Description
`parameters`	`Object`	✓

Returns

Type	Description
`void`	Does not return a value.

dtmf

Sends DTMF (dual-tone multi-frequency) tones. https://docs.cartesia.ai/line/integrations/websocket-api#dtmf-event

dtmf(parameters: Object): void

Parameters

Parameter	Type	Req.	Description
`parameters`	`Object`	✓

Returns

Type	Description
`void`	Does not return a value.

id

Returns the AgentsClient id.

id(): string

Parameters

This method does not accept parameters.

Returns

Type	Description
`string`	The requested string value.

removeEventListener

Removes a handler for the specified Cartesia.AgentsEvents or Cartesia.Events event.

removeEventListener(event: Cartesia.Events | Cartesia.AgentsEvents | string, callback?: (event: object) => any): void

Parameters

Parameter	Type	Req.	Description
`event`	`Cartesia.Events \| Cartesia.AgentsEvents \| string`	✓	Event constant or event name to subscribe to.
`callback`	`(event: object) => any`	✗	Function called when the event is emitted.

Returns

Type	Description
`void`	Does not return a value.

sendMediaTo

Starts sending media from the Cartesia (via WebSocket) to the media unit. Cartesia works in real time.

sendMediaTo(mediaUnit: VoxMediaUnit, parameters?: SendMediaParameters): void

Parameters

Parameter	Type	Req.	Description
`mediaUnit`	`VoxMediaUnit`	✓
`parameters`	`SendMediaParameters`	✗

Returns

Type	Description
`void`	Does not return a value.

start

Initializes the audio stream configuration. https://docs.cartesia.ai/line/integrations/websocket-api#start-event

start(parameters: Object): void

Parameters

Parameter	Type	Req.	Description
`parameters`	`Object`	✓

Returns

Type	Description
`void`	Does not return a value.

stopMediaTo

Stops sending media from the Cartesia (via WebSocket) to the media unit.

stopMediaTo(mediaUnit: VoxMediaUnit): void

Parameters

Parameter	Type	Req.	Description
`mediaUnit`	`VoxMediaUnit`	✓

Returns

Type	Description
`void`	Does not return a value.

webSocketId

Returns the Cartesia WebSocket id.

webSocketId(): string

Parameters

This method does not accept parameters.

Returns

Type	Description
`string`	The requested string value.

Events

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

Events.WebSocketMediaStarted

Triggered when the audio stream sent by a third party through a Cartesia WebSocket starts playing.

Event constant: Events.WebSocketMediaStarted

Payload

Field	Type	Req.	Description
`client`	`AgentsClient`	✓	The Cartesia.AgentsClient instance.
`tag`	`string`	✗	Special 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.
`encoding`	`string`	✗	Audio encoding formats.
`customParameters`	`{ [key: string]: string }`	✗	Custom parameters.

Events.WebSocketMediaEnded

Triggered after the end of the audio stream sent by a third party through a Cartesia WebSocket (1 second of silence).

Event constant: Events.WebSocketMediaEnded

Payload

Field	Type	Req.	Description
`client`	`AgentsClient`	✓	The Cartesia.AgentsClient instance.
`tag`	`string`	✗	Special 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.
`mediaInfo`	`WebSocketMediaInfo`	✗	Information about the audio stream that can be obtained after the stream stops or pauses (1 second of silence).

AgentsEvents

These events mirror server messages from the Cartesia Agents WebSocket API. The data field contains the provider event payload.

Unknown

The unknown event.

Event constant: AgentsEvents.Unknown

Payload

Field	Type	Req.	Description
`client`	`AgentsClient`	✓	The Cartesia.AgentsClient instance.
`data`	`{ customEvent?: string; payload?: Object; }`	✗	This event payload is provider-specific. See the partner event documentation for the full payload shape.

HTTPResponse

The HTTP response event.

Event constant: AgentsEvents.HTTPResponse

Payload

Field	Type	Req.	Description
`client`	`AgentsClient`	✓	The Cartesia.AgentsClient instance.
`data`	`{ customEvent?: string; payload?: Object; }`	✗	This event payload is provider-specific. See the partner event documentation for the full payload shape.

ACK

Server acknowledgment of the start event, confirming stream configuration. https://docs.cartesia.ai/line/integrations/websocket-api#ack-event

Event constant: AgentsEvents.ACK

Payload

Field	Type	Req.	Description
`client`	`AgentsClient`	✓	The Cartesia.AgentsClient instance.
`data`	`{ customEvent?: string; payload?: Object; }`	✗	This event payload is provider-specific. See the partner event documentation for the full payload shape.

Clear

Indicates the agent wants to clear/interrupt the current audio stream. https://docs.cartesia.ai/line/integrations/websocket-api#clear-event

Event constant: AgentsEvents.Clear

Payload

Field	Type	Req.	Description
`client`	`AgentsClient`	✓	The Cartesia.AgentsClient instance.
`data`	`{ customEvent?: string; payload?: Object; }`	✗	This event payload is provider-specific. See the partner event documentation for the full payload shape.

DTMF

Server sends DTMF tones from the agent. https://docs.cartesia.ai/line/integrations/websocket-api#dtmf-event-2

Event constant: AgentsEvents.DTMF

Payload

Field	Type	Req.	Description
`client`	`AgentsClient`	✓	The Cartesia.AgentsClient instance.
`data`	`{ customEvent?: string; payload?: Object; }`	✗	This event payload is provider-specific. See the partner event documentation for the full payload shape.

Custom

Server sends custom metadata from the agent. https://docs.cartesia.ai/line/integrations/websocket-api#custom-event-2

Event constant: AgentsEvents.Custom

Payload

Field	Type	Req.	Description
`client`	`AgentsClient`	✓	The Cartesia.AgentsClient instance.
`data`	`{ customEvent?: string; payload?: Object; }`	✗	The ‘payload’ parameter contains the event’s data.

WebSocketError

The WebSocket error response event.

Event constant: AgentsEvents.WebSocketError

Payload

Field	Type	Req.	Description
`client`	`AgentsClient`	✓	The Cartesia.AgentsClient instance.
`data`	`{ customEvent?: string; payload?: Object; }`	✗	The ‘payload’ parameter contains the event’s data.

ConnectorInformation

Contains information about connector.

Event constant: AgentsEvents.ConnectorInformation

Payload

Field	Type	Req.	Description
`client`	`AgentsClient`	✓	The Cartesia.AgentsClient instance.
`data`	`{ customEvent?: string; payload?: Object; }`	✗	The ‘payload’ parameter contains the event’s data.

Related guides

Contents

Usage

Factory functions

createAgentsClient

createRealtimeTTSPlayer

AgentsClient

Methods

addEventListener

clearMediaBuffer

close

custom

dtmf

id

removeEventListener

sendMediaTo

start

stopMediaTo

webSocketId

Events

Events.WebSocketMediaStarted

Events.WebSocketMediaEnded

AgentsEvents

Unknown

HTTPResponse

ACK

Clear

DTMF

Custom

WebSocketError

ConnectorInformation