> 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

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                                                        |
| -------------------------------------------- | ------------------------------------------------------------------ |
| <code>Promise\<Cartesia.AgentsClient></code> | Resolves to the [`Cartesia.AgentsClient`](#agentsclient) instance. |

### &#x20;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

### &#x20;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` | <code>(event: object) => any</code>                                           | ✓    | Function called when the event is emitted.    |

**Returns**

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

### &#x20;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. |

### &#x20;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. |

### &#x20;custom

Sends custom metadata to the agent. [https://docs.cartesia.ai/line/integrations/web-calls#custom-event](https://docs.cartesia.ai/line/integrations/web-calls#custom-event)

```ts
custom(parameters: Object): void
```

**Parameters**

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

**Returns**

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

### &#x20;dtmf

Sends DTMF (dual-tone multi-frequency) tones. [https://docs.cartesia.ai/line/integrations/web-calls#dtmf-event](https://docs.cartesia.ai/line/integrations/web-calls#dtmf-event)

```ts
dtmf(parameters: Object): void
```

**Parameters**

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

**Returns**

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

### &#x20;id

Returns the AgentsClient id.

```ts
id(): string
```

**Parameters**

This method does not accept parameters.

**Returns**

| Type     | Description                 |
| -------- | --------------------------- |
| `string` | The requested string value. |

### &#x20;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` | <code>(event: object) => any</code>                                           | ✗    | Function called when the event is emitted.    |

**Returns**

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

### &#x20;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. |

### &#x20;start

Initializes the audio stream configuration. [https://docs.cartesia.ai/line/integrations/web-calls#start-event](https://docs.cartesia.ai/line/integrations/web-calls#start-event)

```ts
start(parameters: Object): void
```

**Parameters**

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

**Returns**

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

### &#x20;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. |

### &#x20;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.

### &#x20;WebSocketMediaStarted

Triggered when the audio stream sent by a third party through a Cartesia WebSocket is started 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> | <code>\{ \[key: string]: string }</code> | ✗    | Custom parameters.                                                                                                                                |

### &#x20;WebSocketMediaEnded

Triggers 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.

<a id="-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`   | `Object`       | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.cartesia.ai/line/integrations/web-calls) for the full payload shape. |

<a id="-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`   | `Object`       | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.cartesia.ai/line/integrations/web-calls) for the full payload shape. |

<a id="-ack" />

Server acknowledgment of the start event, confirming stream configuration. [https://docs.cartesia.ai/line/integrations/web-calls#ack-event](https://docs.cartesia.ai/line/integrations/web-calls#ack-event)

Event constant: `AgentsEvents.ACK`

**Payload**

| Field    | Type           | Req. | Description                                                                                                                                                                |
| -------- | -------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client` | `AgentsClient` | ✓    | The [Cartesia.AgentsClient](/api-reference/voxengine/cartesia#agentsclient) instance.                                                                                      |
| `data`   | `Object`       | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.cartesia.ai/line/integrations/web-calls#ack-event) for the full payload shape. |

<a id="-clear" />

Indicates the agent wants to clear/interrupt the current audio stream. [https://docs.cartesia.ai/line/integrations/web-calls#clear-event](https://docs.cartesia.ai/line/integrations/web-calls#clear-event)

Event constant: `AgentsEvents.Clear`

**Payload**

| Field    | Type           | Req. | Description                                                                                                                                                                  |
| -------- | -------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client` | `AgentsClient` | ✓    | The [Cartesia.AgentsClient](/api-reference/voxengine/cartesia#agentsclient) instance.                                                                                        |
| `data`   | `Object`       | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.cartesia.ai/line/integrations/web-calls#clear-event) for the full payload shape. |

<a id="-dtmf" />

Server sends DTMF tones from the agent. [https://docs.cartesia.ai/line/integrations/web-calls#dtmf-event-2](https://docs.cartesia.ai/line/integrations/web-calls#dtmf-event-2)

Event constant: `AgentsEvents.DTMF`

**Payload**

| Field    | Type           | Req. | Description                                                                                                                                                                   |
| -------- | -------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client` | `AgentsClient` | ✓    | The [Cartesia.AgentsClient](/api-reference/voxengine/cartesia#agentsclient) instance.                                                                                         |
| `data`   | `Object`       | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.cartesia.ai/line/integrations/web-calls#dtmf-event-2) for the full payload shape. |

<a id="-custom" />

Server sends custom metadata from the agent. [https://docs.cartesia.ai/line/integrations/web-calls#custom-event-2](https://docs.cartesia.ai/line/integrations/web-calls#custom-event-2)

Event constant: `AgentsEvents.Custom`

**Payload**

| Field    | Type           | Req. | Description                                                                           |
| -------- | -------------- | ---- | ------------------------------------------------------------------------------------- |
| `client` | `AgentsClient` | ✓    | The [Cartesia.AgentsClient](/api-reference/voxengine/cartesia#agentsclient) instance. |
| `data`   | `Object`       | ✗    | The event's data.                                                                     |

<a id="-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`   | `Object`       | ✗    | The event's data.                                                                     |

<a id="-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`   | `Object`       | ✗    | The event's data.                                                                     |