> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Avatars

> Configure Telnyx avatars for AI Assistant conversations, select a model and background, and control avatar conversations from a server-side WebSocket client.

**Beta:** AI Assistant avatars are in beta.

Add an avatar to an existing assistant with `avatar_settings`. The assistant keeps its instructions, voice, tools and transcription configuration. Each conversation opts into the saved avatar with `avatar=true`; saving an avatar does not turn every conversation into a video session.

## Voice compatibility

AI Assistant avatars are compatible only with TTS voices whose provider is **Telnyx**. ElevenLabs and other third-party TTS providers are not supported for avatar conversations, including Portal avatar tests.

Configure the voice through `voice_settings`; `avatar_settings.provider` selects the avatar provider, not the TTS provider.

## Pricing

During October 2026, Telnyx avatars are included in AI Assistant call pricing at no additional charge. Starting November 1, 2026, avatar usage costs **\$0.08 USD per minute**, in addition to standard AI Assistant call charges.

The same pricing applies to avatar tests in the Portal.

## Configure an avatar

Send the following request body to [Update an assistant](/api-reference/assistants/update-an-assistant), `POST /v2/ai/assistants/{assistant_id}`. The same `avatar_settings` object is accepted when creating an assistant.

`avatar_settings.model` is required. It selects the avatar rendering model, independently of the assistant's top-level LLM `model` and `voice_settings`.

```json theme={null}
{
  "avatar_settings": {
    "provider": "telnyx",
    "model": "foxtrot-1",
    "avatar_id": "elena",
    "background_id": "studio"
  }
}
```

| Setting | Supported values |
| - | - |
| `model` | `foxtrot-1` |
| `avatar_id` | `elena`, `ben`, `jordan`, `lin`, `avery`, `raphael`, or an organization-owned custom avatar ID returned by the Avatars API |
| `background_id` | `office`, `studio`, `reception` |

The Portal defaults new avatar configurations to `studio`.

The avatar's appearance and voice are configured separately. Select the voice through `voice_settings`. The Portal offers an optional suggested Telnyx Ultra voice pairing for each Telnyx avatar; selecting an avatar alone does not change the voice.

## Start an avatar conversation

Open the assistant conversation WebSocket with `avatar=true`:

```text theme={null}
wss://api.telnyx.com/v2/ai/assistants/{assistant_id}/conversation?avatar=true&input_sample_rate=16000
```

Connect from a server-side WebSocket client using a Telnyx API v2 key in the `Authorization: Bearer` header. Keep the key on your server. See [Connect and authenticate](/docs/inference/ai-assistants/realtime-conversations#connect-and-authenticate) for Node.js and Python examples.

The WebSocket carries PCM input audio, conversation events and avatar signaling. Avatar video is delivered separately over WebRTC, not as video frames on this WebSocket. The server-side integration must handle the media signaling contract in the [WebSocket reference](/api-reference/websockets/talk-to-an-ai-assistant-over-websocket).

1. Send `session.update` as the first frame, even when no dynamic variables are needed.
2. Handle the avatar signaling exchange and send `avatar.media.ready` once the media receiver is ready.
3. Wait for `session.created`, then stream PCM input audio and process conversation events. While the avatar is active, consume its synchronized audio and video together; do not also play WebSocket audio deltas.

Complete avatar setup within 60 seconds of opening the connection. Closing the WebSocket ends the session; stop local microphone capture and close the WebRTC connection too. See the [WebSocket reference](/api-reference/websockets/talk-to-an-ai-assistant-over-websocket) for payload schemas. An avatar failure before `session.created` is fatal and closes the WebSocket with code `1011`. A runtime `avatar.error` with `error.fatal: false` keeps the conversation open: stop WebRTC playback, continue sending microphone audio, and switch to subsequent WebSocket `response.output_audio.delta` frames using the output format from `session.created`. See [Avatar errors](/docs/inference/ai-assistants/realtime-conversations#avatar-errors) for the complete fallback and retry behavior.

## Test and choose a conversation mode

For an assistant with saved avatar settings, **Call your assistant** in the Portal offers **With avatar (BETA)** or **Without avatar**. The avatar option is selected by default and uses the conversation WebSocket. The voice-only option uses the existing voice call test.

For **With avatar (BETA)**, optional dynamic-variable test values are sent in the first `session.update` frame. Nonempty test values override the same-named variables for that conversation only; blank fields leave saved defaults or webhook values in effect. Testing does not update the assistant configuration. See [Pass dynamic variables](/docs/inference/ai-assistants/realtime-conversations#pass-dynamic-variables) for the WebSocket payload.

Avatar tests follow the [avatar pricing](#pricing) above. Phone-call tools such as transfer and DTMF are not supported in the avatar WebSocket session. PSTN calls remain voice-only. For your own WebSocket client, omit `avatar` or set `avatar=false` to start a voice-only conversation while keeping the saved avatar configuration.

## Remove the saved avatar

Update the assistant with:

```json theme={null}
{
  "avatar_settings": null
}
```

This removes the assistant's avatar configuration. Omitting `avatar_settings` from an update leaves the current configuration unchanged.