AI Widget

Replace the stored AI Widget appearance for an app

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).

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

Path parameters

appIdstring required

Target App ID. Must be an app the calling actor owns or has been delegated access to.

Request body

appearanceobject required

Example request

{
  "appearance": {
    "data-primary-color": "#0052cc",
    "data-position": "left",
    "data-greeting": "Hi! How can we help?"
  }
}

Response

The stored set, values normalised.

{ ok: true, appearance: { [attribute: string]: string } }

Changes

No recorded changes to this operation across all 1 revision of this API.