Digital Avatars

Show a Telnyx AI Assistant’s avatar as the bot’s camera, lip-synced to the assistant’s own speech.

Beta: digital avatars in meetings are in beta.

Instead of a plain roster entry, a bot running a Telnyx AI Assistant can appear on camera as that assistant’s avatar. Telnyx renders the avatar — lip-synced video and audio — from the assistant’s own conversation, and the bot streams it as its camera. This suits branded, customer-facing, or demo meetings where a personified presence matters.

The avatar is configured on the assistant, not on the meeting session. Add avatar_settings to the assistant first — see Configure an avatar, including its voice requirements. Then opt the session in with assistant.avatar:

curl -X POST https://api.telnyx.com/v2/meeting_sessions \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "meeting_url": "https://meet.google.com/abc-defg-hij",
    "bot_name": "AI Assistant",
    "assistant": {
      "id": "assistant-6207ab25-b185-478f-b2ef-85159e226727",
      "avatar": true,
      "audio_gate": "full_duplex",
      "leave_on_end": true
    }
  }'

Field	Type	Description
assistant.avatar	boolean	Show the avatar saved on the assistant as the bot’s camera. false by default: the assistant speaks without video. Requires assistant.

The request carries no avatar ID or key. At creation the service reads the assistant and rejects the request if it has no Telnyx avatar configured, before any bot is sent to the meeting. The rest of the assistant parameters work as usual.

How It Works

• The assistant owns the avatar’s speech. Only the assistant’s conversation is rendered, so speak and stop_speaking return 409 invalid_state, and speak_on_enter is rejected with 400 invalid_request — the assistant greets through its avatar instead. chat_on_enter works as usual.
• Startup takes a few seconds. The bot shows an Avatar starting frame until the avatar’s video is playing; avatar_state then becomes connected and the assistant’s greeting starts. Read avatar_state rather than assuming the camera is ready.
• Interruption follows the assistant. With audio_gate: "full_duplex", the assistant’s own interruption handling stops the avatar when a participant genuinely interrupts it; short backchannels such as “mm-hmm” do not cut it off. With half_duplex, the assistant does not hear the room while the avatar speaks, as without an avatar.
• Immediate REST creates only. join_at is not supported, avatars are not available through calendar auto-join or the MCP server, and avatar mode is chosen at creation and cannot be toggled mid-meeting.
• Platforms. Google Meet, Zoom, Teams, and Webex. Other meeting URLs are rejected with 422 unsupported_capability.
• Recording. The avatar’s camera video is not included in the recording; the bot’s audio is.
• Camera image. The avatar takes precedence over a static camera_image: the image is ignored and its URL is not fetched.

Avatar State

The session response carries the avatar captured from the assistant at creation, and its state:

"avatar": { "provider": "telnyx", "model": "foxtrot-1", "avatar_id": "elena", "background_id": "studio" },
"avatar_state": "connected",
"avatar_state_changed_at": "2026-10-12T12:00:00.000Z"

avatar_state is starting, connected, degraded, or disconnected, and each change is recorded as an avatar.connected, avatar.degraded, or avatar.disconnected session event. All three fields are null on a session without an avatar.

Voice-only Fallback

If the avatar cannot start, or stops working mid-meeting, the session continues voice-only: the bot shows a Voice only frame and plays the assistant’s audio itself.

• Before the avatar is live, the assistant’s conversation restarts once without the avatar. A second failure fails the assistant as it would without an avatar.
• After the avatar is live, the remaining speech switches to voice-only without interrupting the conversation. The utterance in flight is not replayed.

Either way avatar_state becomes degraded, and the avatar.degraded event carries one of these reasons:

Reason	Meaning
telnyx_avatar_unavailable	Telnyx could not start the avatar — for example, setup did not finish in time, or the avatar was removed from the assistant after the session was created.
telnyx_avatar_ended	Telnyx ended the avatar mid-session.
webrtc_failed	The bot’s media connection to the avatar failed.
video_autoplay_blocked_muted	The bot’s browser could not play the avatar video.
speech_processing_failed	Voice-only playback failed for one utterance. The session keeps running.

Telnyx ends the avatar shortly before an hour into the session; a longer meeting continues voice-only with telnyx_avatar_ended.

Troubleshooting

Symptom	Typical cause
400 invalid_request, message starts assistant_avatar_not_configured:	The assistant has no Telnyx avatar_settings. Configure an avatar on it and retry.
400 invalid_request, message starts assistant_not_found:	The assistant does not exist or does not belong to this account.
400 invalid_request on a top-level avatar object	The earlier bring-your-own-key avatar object has been removed. Set assistant.avatar: true on an assistant with an avatar configured.
400 invalid_request with speak_on_enter	Not supported with an avatar. Let the assistant greet, or use chat_on_enter.
409 invalid_state, message starts avatar_requires_assistant_speech:	speak or stop_speaking was sent to an avatar session.
422 unsupported_capability	The meeting platform does not support the bot’s camera output.
503 assistant_lookup_unavailable	The assistant could not be read. No bot was created; retry.

Related

• Telnyx AI Assistants — attach the assistant the avatar belongs to
• AI Assistant avatars — configure the avatar, model, and background on the assistant
• Meeting Presence — the bot’s roster name and identity choices
• Still images — a static camera tile instead of an avatar