> For a complete documentation index, fetch https://docs.voximplant.ai/llms.txt

# Cartesia

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.

## Related guides

#### [Cartesia connector overview](/voice-ai-orchestration/cartesia/overview)

Learn how Cartesia Line fits into a VoxEngine call flow.

## Contents

* [Usage](#usage): required module import and basic flow.
* [Factory functions](#factory-functions): create the Cartesia Agents client.
* [Methods](#methods): start, DTMF, and custom agent messages.
* [Events](#events): WebSocket media bridge events.
* [AgentsEvents](#agentsevents): Cartesia Agents event names and payload fields.

## Usage

Add the module before using the namespace:

```js
require(Modules.Cartesia);
```

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

## Factory functions

### createAgentsClient

Creates a [Cartesia.AgentsClient](/api-reference/voxengine/cartesia#agentsclient) instance.

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

**Parameters**

| Parameter    | Type                                       | Req. | Description |
| ------------ | ------------------------------------------ | ---- | ----------- |
| `parameters` | <code>AgentsClient<wbr />Parameters</code> | ✓    |             |

**Returns**

| Type                             | Description                                                        |
| -------------------------------- | ------------------------------------------------------------------ |
| `Promise<Cartesia.AgentsClient>` | Resolves to the [`Cartesia.AgentsClient`](#agentsclient) instance. |

### createRealtimeTTSPlayer

Creates a new [Cartesia.RealtimeTTSPlayer](/api-reference/voxengine/cartesia/realtime-tts-player) 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.

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

**Parameters**

| Parameter    | Type                                                   | Req. | Description |
| ------------ | ------------------------------------------------------ | ---- | ----------- |
| `text`       | `string`                                               | ✓    |             |
| `parameters` | <code>RealtimeTTS<wbr />Player<wbr />Parameters</code> | ✗    |             |

**Returns**

| Type                                  | Description                              |
| ------------------------------------- | ---------------------------------------- |
| <code>RealtimeTTS<wbr />Player</code> | The requested `RealtimeTTSPlayer` value. |

## AgentsClient

## Methods

### addEventListener

Adds a handler for the specified [Cartesia.AgentsEvents](/api-reference/voxengine/cartesia#agentsevents) or [Cartesia.Events](/api-reference/voxengine/cartesia#events) event. Use only functions as handlers; anything except a function leads to the error and scenario termination when a handler is called.

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

**Parameters**

| Parameter  | Type                                                                          | Req. | Description                                   |
| ---------- | ----------------------------------------------------------------------------- | ---- | --------------------------------------------- |
| `event`    | <code>Cartesia.<wbr />Events \| Cartesia.<wbr />AgentsEvents \| string</code> | ✓    | 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.

```ts
clearMediaBuffer(parameters?: ClearMediaBufferParameters): void
```

**Parameters**

| Parameter    | Type                                                  | Req. | Description |
| ------------ | ----------------------------------------------------- | ---- | ----------- |
| `parameters` | <code>ClearMedia<wbr />Buffer<wbr />Parameters</code> | ✗    |             |

**Returns**

| Type   | Description              |
| ------ | ------------------------ |
| `void` | Does not return a value. |

### close

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

```ts
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](https://docs.cartesia.ai/line/integrations/websocket-api#custom-event)

```ts
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](https://docs.cartesia.ai/line/integrations/websocket-api#dtmf-event)

```ts
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.

```ts
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](/api-reference/voxengine/cartesia#agentsevents) or [Cartesia.Events](/api-reference/voxengine/cartesia#events) event.

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

**Parameters**

| Parameter  | Type                                                                          | Req. | Description                                   |
| ---------- | ----------------------------------------------------------------------------- | ---- | --------------------------------------------- |
| `event`    | <code>Cartesia.<wbr />Events \| Cartesia.<wbr />AgentsEvents \| string</code> | ✓    | 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.

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

**Parameters**

| Parameter    | Type                                    | Req. | Description |
| ------------ | --------------------------------------- | ---- | ----------- |
| `mediaUnit`  | `VoxMediaUnit`                          | ✓    |             |
| `parameters` | <code>SendMedia<wbr />Parameters</code> | ✗    |             |

**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](https://docs.cartesia.ai/line/integrations/websocket-api#start-event)

```ts
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.

```ts
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.

```ts
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](/api-reference/voxengine/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.                                                                                                                           |
| <code>custom<wbr />Parameters</code> | `{ [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](/api-reference/voxengine/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` | <code>WebSocket<wbr />MediaInfo</code> | ✗    | 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](/api-reference/voxengine/cartesia#agentsclient) instance.                                                                                |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.cartesia.ai/line/integrations/websocket-api) for the full payload shape. |

#### HTTPResponse

The HTTP response event.

Event constant: `AgentsEvents.HTTPResponse`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                                                                                          |
| -------- | ---------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client` | `AgentsClient`                                                   | ✓    | The [Cartesia.AgentsClient](/api-reference/voxengine/cartesia#agentsclient) instance.                                                                                |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.cartesia.ai/line/integrations/websocket-api) 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](https://docs.cartesia.ai/line/integrations/websocket-api#ack-event)

Event constant: `AgentsEvents.ACK`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `client` | `AgentsClient`                                                   | ✓    | The [Cartesia.AgentsClient](/api-reference/voxengine/cartesia#agentsclient) instance.                                                                                          |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.cartesia.ai/line/integrations/websocket-api#ack-event) 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](https://docs.cartesia.ai/line/integrations/websocket-api#clear-event)

Event constant: `AgentsEvents.Clear`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                                                                                                      |
| -------- | ---------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client` | `AgentsClient`                                                   | ✓    | The [Cartesia.AgentsClient](/api-reference/voxengine/cartesia#agentsclient) instance.                                                                                            |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.cartesia.ai/line/integrations/websocket-api#clear-event) for the full payload shape. |

#### DTMF

Server sends DTMF tones from the agent. [https://docs.cartesia.ai/line/integrations/websocket-api#dtmf-event-2](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](/api-reference/voxengine/cartesia#agentsclient) instance.                                                                                             |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.cartesia.ai/line/integrations/websocket-api#dtmf-event-2) for the full payload shape. |

#### Custom

Server sends custom metadata from the agent. [https://docs.cartesia.ai/line/integrations/websocket-api#custom-event-2](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](/api-reference/voxengine/cartesia#agentsclient) instance. |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | 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](/api-reference/voxengine/cartesia#agentsclient) instance. |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | 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](/api-reference/voxengine/cartesia#agentsclient) instance. |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | The 'payload' parameter contains the event's data.                                    |

> Agents WebSocket client for Cartesia Line voice agent scenarios.

## Docs

- [RealtimeTTSPlayer](https://docs.voximplant.ai/api-reference/voxengine/cartesia/realtime-tts-player.md)