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

# session.update

Updates the mode, active avatar, or registered source image. Omitted fields stay unchanged. Only the session state listed below is mutable; this does not update voice, tools, or prompts. `session.updated` acknowledges acceptance. For visual changes, also listen for `session.update.done`.

## Event fields

<ParamField body="event_id" type="string">
  Client-generated id for this event.
</ParamField>

<ParamField body="type" type="string" required>
  Event type. Must be `session.update`.
</ParamField>

<ParamField body="session" type="object" required>
  Partial session state to update.
</ParamField>

<ParamField body="session.mode" type="string">
  New session mode. Supported values are `text_chat` and `video_avatar`. Switching to `text_chat` clears the effective `source_image_id` to `null`. Switching to `video_avatar` requires a renderable active avatar; if `source_image_id` is omitted, Vivix uses the current source image or derives one from the active avatar's `visual.default_source_image_id`.
</ParamField>

<ParamField body="session.active_avatar_id" type="string">
  Avatar whose instructions should apply by default for later responses. In `video_avatar` mode, this is also the avatar rendered in the video stream.
</ParamField>

<ParamField body="session.source_image_id" type="string | null">
  Source image to use for avatar video. Used only in `video_avatar` mode. Use `null` to clear the selected source image; the effective value is also `null` in `text_chat` mode. Requests fail in `video_avatar` mode if no usable source image can be resolved.
</ParamField>

<RequestExample>
  ```json session.update theme={null}
  {
    "event_id": "evt_session_update_001",
    "type": "session.update",
    "session": {
      "mode": "video_avatar",
      "active_avatar_id": "host_a",
      "source_image_id": "side"
    }
  }
  ```
</RequestExample>