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

# Ultravox

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

Use `Ultravox.createWebSocketAPIClient(...)` to create a `WebSocketAPIClient` for the current scenario.

## Related guides

#### [Ultravox connector overview](/voice-ai-orchestration/ultravox/overview)

Learn how Ultravox fits into a VoxEngine call flow.

## Contents

* [Usage](#usage): required module import and basic flow.
* [Factory functions](#factory-functions): create the Ultravox WebSocket API client.
* [Methods](#methods): client-to-server data messages and media helpers.
* [Events](#events): WebSocket media bridge events.
* [WebSocketAPIEvents](#websocketapievents): Ultravox WebSocket API event names and payload fields.

## Usage

Add the module before using the namespace:

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

Create the client, bridge media, and listen for Ultravox WebSocket API events.

## Factory functions

### createWebSocketAPIClient

Creates a new [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) instance.

```ts
createWebSocketAPIClient(parameters: WebSocketAPIClientParameters): Promise<Ultravox.WebSocketAPIClient>
```

**Parameters**

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

**Returns**

| Type                                   | Description                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------ |
| `Promise<Ultravox.WebSocketAPIClient>` | Resolves to the [`Ultravox.WebSocketAPIClient`](#websocketapiclient) instance. |

## WebSocketAPIClient

## Methods

### addEventListener

Adds a handler for the specified [Ultravox.WebSocketAPIEvents](/api-reference/voxengine/ultravox#websocketapievents) or [Ultravox.Events](/api-reference/voxengine/ultravox#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: Ultravox.Events | Ultravox.WebSocketAPIEvents | string, callback: (event: object) => any): void
```

**Parameters**

| Parameter  | Type                                                                                       | Req. | Description                                   |
| ---------- | ------------------------------------------------------------------------------------------ | ---- | --------------------------------------------- |
| `event`    | <code>Ultravox.<wbr />Events \| Ultravox.<wbr />WebSocketAPI<wbr />Events \| 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 Ultravox 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. |

### clientToolResult

Contains the result of a client tool invocation. [https://docs.ultravox.ai/apps/datamessages#clienttoolresult-and-dataconnectiontoolresult](https://docs.ultravox.ai/apps/datamessages#clienttoolresult-and-dataconnectiontoolresult)

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

**Parameters**

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

**Returns**

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

### close

Closes the Ultravox 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. |

### dataConnectionToolResult

Contains the result of a client tool invocation. [https://docs.ultravox.ai/apps/datamessages#clienttoolresult-and-dataconnectiontoolresult](https://docs.ultravox.ai/apps/datamessages#clienttoolresult-and-dataconnectiontoolresult)

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

**Parameters**

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

**Returns**

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

### forcedAgentMessage

Forces the agent to say a specific message or invoke tools. [https://docs.ultravox.ai/apps/datamessages#forcedagentmessage](https://docs.ultravox.ai/apps/datamessages#forcedagentmessage)

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

**Parameters**

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

**Returns**

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

### hangUp

Instructs the agent to end the call with an optional farewell message. [https://docs.ultravox.ai/apps/datamessages#hangup](https://docs.ultravox.ai/apps/datamessages#hangup)

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

**Parameters**

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

**Returns**

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

### id

Returns the WebSocketAPIClient id.

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

**Parameters**

This method does not accept parameters.

**Returns**

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

### inputTextMessage

> **Deprecated**
>
> Used to send a user message to the agent via text.
> NOTE: this method is deprecated, use **userTextMessage** instead.

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

**Parameters**

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

**Returns**

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

### removeEventListener

Removes a handler for the specified [Ultravox.WebSocketAPIEvents](/api-reference/voxengine/ultravox#websocketapievents) or [Ultravox.Events](/api-reference/voxengine/ultravox#events) event.

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

**Parameters**

| Parameter  | Type                                                                                       | Req. | Description                                   |
| ---------- | ------------------------------------------------------------------------------------------ | ---- | --------------------------------------------- |
| `event`    | <code>Ultravox.<wbr />Events \| Ultravox.<wbr />WebSocketAPI<wbr />Events \| 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 Ultravox (via WebSocket) to the media unit. Ultravox 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. |

### setOutputMedium

Sets server’s output medium to text or voice. [https://docs.ultravox.ai/apps/datamessages#setoutputmedium](https://docs.ultravox.ai/apps/datamessages#setoutputmedium)

```ts
setOutputMedium(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 Ultravox (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. |

### userTextMessage

A user message sent via text. The message appears to the agent as if it came from the user. [https://docs.ultravox.ai/apps/datamessages#usertextmessage](https://docs.ultravox.ai/apps/datamessages#usertextmessage)

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

**Parameters**

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

**Returns**

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

### webSocketId

Returns the Ultravox 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 Ultravox WebSocket media bridge.

### Events.WebSocketMediaStarted

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

Event constant: `Events.WebSocketMediaStarted`

**Payload**

| Field                                | Type                                   | Req. | Description                                                                                                                                       |
| ------------------------------------ | -------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client`                             | <code>WebSocketAPI<wbr />Client</code> | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) 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 an Ultravox WebSocket (**1 second of silence**).

Event constant: `Events.WebSocketMediaEnded`

**Payload**

| Field       | Type                                   | Req. | Description                                                                                                                                       |
| ----------- | -------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client`    | <code>WebSocketAPI<wbr />Client</code> | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) 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**).                               |

## WebSocketAPIEvents

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

#### Unknown

The unknown event.

Event constant: `WebSocketAPIEvents.Unknown`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                                                                            |
| -------- | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `client` | <code>WebSocketAPI<wbr />Client</code>                           | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) instance.                                                      |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.ultravox.ai/apps/datamessages) for the full payload shape. |

#### HTTPResponse

The HTTP response event.

Event constant: `WebSocketAPIEvents.HTTPResponse`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                                                                            |
| -------- | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `client` | <code>WebSocketAPI<wbr />Client</code>                           | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) instance.                                                      |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.ultravox.ai/apps/datamessages) for the full payload shape. |

#### State

Indicates the server’s current state. [https://docs.ultravox.ai/apps/datamessages#state](https://docs.ultravox.ai/apps/datamessages#state)

Event constant: `WebSocketAPIEvents.State`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                                                                                  |
| -------- | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `client` | <code>WebSocketAPI<wbr />Client</code>                           | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) instance.                                                            |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.ultravox.ai/apps/datamessages#state) for the full payload shape. |

#### Transcript

Contains text for an utterance made during the call. [https://docs.ultravox.ai/apps/datamessages#transcript](https://docs.ultravox.ai/apps/datamessages#transcript)

Event constant: `WebSocketAPIEvents.Transcript`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                                                                                       |
| -------- | ---------------------------------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client` | <code>WebSocketAPI<wbr />Client</code>                           | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) instance.                                                                 |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.ultravox.ai/apps/datamessages#transcript) for the full payload shape. |

#### ClientToolInvocation

Sent by the server to ask the client or data connection to invoke a tool with the given parameters. [https://docs.ultravox.ai/apps/datamessages#clienttoolinvocation-and-dataconnectiontoolinvocation](https://docs.ultravox.ai/apps/datamessages#clienttoolinvocation-and-dataconnectiontoolinvocation)

Event constant: `WebSocketAPIEvents.ClientToolInvocation`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                                                                            |
| -------- | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `client` | <code>WebSocketAPI<wbr />Client</code>                           | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) instance.                                                      |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | This event payload is provider-specific. See the [partner event documentation](https://docs.ultravox.ai/apps/datamessages) for the full payload shape. |

#### DataConnectionToolInvocation

Sent by the server to ask the client or data connection to invoke a tool with the given parameters. [https://docs.ultravox.ai/apps/datamessages#clienttoolinvocation-and-dataconnectiontoolinvocation](https://docs.ultravox.ai/apps/datamessages#clienttoolinvocation-and-dataconnectiontoolinvocation)

Event constant: `WebSocketAPIEvents.DataConnectionToolInvocation`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                       |
| -------- | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------- |
| `client` | <code>WebSocketAPI<wbr />Client</code>                           | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) instance. |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | The 'payload' parameter contains the event's data.                                                |

#### Debug

Useful for application debugging. [https://docs.ultravox.ai/apps/datamessages#debug](https://docs.ultravox.ai/apps/datamessages#debug)

Event constant: `WebSocketAPIEvents.Debug`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                       |
| -------- | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------- |
| `client` | <code>WebSocketAPI<wbr />Client</code>                           | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) instance. |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | The 'payload' parameter contains the event's data.                                                |

#### PlaybackClearBuffer

Used to clear buffered output audio. WebSocket only. [https://docs.ultravox.ai/apps/datamessages#playbackclearbuffer](https://docs.ultravox.ai/apps/datamessages#playbackclearbuffer)

Event constant: `WebSocketAPIEvents.PlaybackClearBuffer`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                       |
| -------- | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------- |
| `client` | <code>WebSocketAPI<wbr />Client</code>                           | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) 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: `WebSocketAPIEvents.WebSocketError`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                       |
| -------- | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------- |
| `client` | <code>WebSocketAPI<wbr />Client</code>                           | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) 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: `WebSocketAPIEvents.ConnectorInformation`

**Payload**

| Field    | Type                                                             | Req. | Description                                                                                       |
| -------- | ---------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------- |
| `client` | <code>WebSocketAPI<wbr />Client</code>                           | ✓    | The [Ultravox.WebSocketAPIClient](/api-reference/voxengine/ultravox#websocketapiclient) instance. |
| `data`   | <code>\{ custom<wbr />Event?: string; payload?: Object; }</code> | ✗    | The 'payload' parameter contains the event's data.                                                |

> WebSocket API client for Ultravox real-time agent scenarios.