---
title: "Replace the stored AI Widget appearance for an app"
method: PUT
path: "/v2/apps/{appId}/widget/appearance"
tags: ["AI Widget"]
---

# Replace the stored AI Widget appearance for an app

`PUT /v2/apps/{appId}/widget/appearance`

## Request

- Base URL: `https://api.chat.ethora.com`
- URL: `https://api.chat.ethora.com/v2/apps/{appId}/widget/appearance`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Replaces the stored appearance with `appearance`, a map of `data-*`
attribute names to values. Send only the values that differ from the
widget's defaults; `{}` clears everything. Numbers and booleans are
accepted and stored as strings; a `null` value drops that attribute.

The embed reads the stored set at load (through `GET /v2/widget/config`) as
the lowest layer: attributes written on the snippet and URL parameters
override it.

Every attribute is checked against an allowlist, and the whole request is
rejected (422) if any name is unknown or any value invalid:
- text: `data-title`, `data-greeting-title` (120 chars), `data-greeting`
  (500), `data-greeting-message` (1000), `data-cta-text` (160); no control
  characters.
- colors (hex, rgb/rgba/hsl/hsla, or a color name): `data-primary-color`,
  `data-secondary-color`, `data-icons-color`, `data-own-bubble-bg`,
  `data-other-bubble-bg`, `data-input-bg`.
- `data-launcher-gradient`: two colors separated by a comma.
- sizes (number with px, %, vw, vh, svh, dvh, rem or em, or a `calc()`):
  `data-font-size`, `data-width`, `data-height`, `data-expanded-width`,
  `data-expanded-height`, `data-expanded-inset`.
- booleans (`true`/`false`, `1`/`0`, `yes`/`no`, stored as `true` or
  `false`): `data-hide-system-messages`, `data-disable-media`,
  `data-allow-fullscreen`, `data-start-fullscreen`, `data-flat-launcher`,
  `data-launcher-glow`, `data-cta-sparkle`.
- integers: `data-launcher-size` (24 to 160), `data-cta-delay` (0 to 600000).
- `data-position`: `left` or `right`.
- `data-locale`: a language tag such as `en` or `pt-BR`.
- `data-font-family`: letters, digits, spaces, commas, quotes, `_` and `-`
  (120 chars).
- `data-google-font`: a Google Fonts family spec (120 chars).
- `data-launcher-icon`: an http(s) URL.

Identity attributes (`data-app-id`, `data-api-base`, `data-bot-id`) cannot be
stored: a saved setting never repoints the widget at another App, bot or
backend.

Auth: tenantActor, with App settings update access (the App's creator
always has it).

## Path parameters

- `appId` string, required

## Request body

- object
  - `appearance` object, required

## Response `200`

The stored set, values normalised.
```
{ ok: true, appearance: { [attribute: string]: string } }
```

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Caller has no access to this app.
- `404`: ``` { error: 'App not found', code: 'APP_NOT_FOUND' } ```
- `422`: `appearance` missing or not an object, or attributes that are unknown or hold invalid values (all named in the message). ``` { error: 'Invalid widget appearance: data-foo (not a widget appearance attribute), ...', code: 'VALIDATION_ERROR' } ```
- `500`: Internal Server Error

---

[API](https://skmtc.dev/ethora/apis/platform-api.md) · [All operations](https://skmtc.dev/ethora/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ethora/apis/platform-api/revisions/01b6e64378ee?raw)