Skip to main content
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.

​
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, 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.
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:
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 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.
  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 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 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 for the WebSocket payload. Avatar tests follow the avatar 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:
This removes the assistant’s avatar configuration. Omitting avatar_settings from an update leaves the current configuration unchanged.