PUThttps://app.evoriqa.com/api/v1/chatbots/{chatbotId}/appearance

Save widget appearance

Saves the appearance bundle in one write — the dashboard's appearance editor as an API call. `settings` accepts the same fields (and validation) as PATCH /settings.

Requires scope chatbots:write

Access is gated — enable it before your first call

The API is off by default. A request succeeds only when all three switches are on: the platform master switch (off by default), your organisation’s API toggle, and your plan or client entitlement. Any one off returns 403 API access is not enabled for this workspace.

Parameters

Name	In	Type	Required	Default	Description
chatbotId	path	string uuid	Required	—	The chatbot's id.

Request body

Content type: application/json

Field	Type	Required	Description
chatbot	object	Required	The chatbot display fields the appearance editor owns. The key is required; both fields inside it are optional.
chatbot.botName	string 1–120 chars	Optional	The name the widget shows.
chatbot.greetingMessage	string up to 500 chars, or null	Optional	First message the widget shows. Null clears it.
settings	string	Required	The widget settings, validated exactly as in PATCH /settings. The key is required; send `{}` to leave the settings untouched.
settings.primaryColor	string matches `^#([0-9a-fA-F]{3}\|[0-9a-fA-F]{6})$`	Optional	Widget accent colour.
settings.secondaryColor	string matches `^#([0-9a-fA-F]{3}\|[0-9a-fA-F]{6})$`, or null	Optional	Secondary colour.
settings.backgroundColor	string matches `^#([0-9a-fA-F]{3}\|[0-9a-fA-F]{6})$`, or null	Optional	Chat background colour.
settings.textColor	string matches `^#([0-9a-fA-F]{3}\|[0-9a-fA-F]{6})$`, or null	Optional	Message text colour.
settings.bubbleColor	string matches `^#([0-9a-fA-F]{3}\|[0-9a-fA-F]{6})$`, or null	Optional	Launcher bubble colour.
settings.position	string one of `bottom-right` · `bottom-left`	Optional	Widget corner.
settings.showPoweredBy	boolean	Optional	Show the “powered by” footer.
settings.showSources	boolean	Optional	Show source citations under answers.
settings.blockedTopics	array up to 25 items	Optional	Topics the bot declines across every channel (best-effort AI enforcement). Send [] to clear.
settings.refusalMessage	string up to 300 chars, or null	Optional	Custom refusal wording for blocked topics; null falls back to the default fallback message.
settings.collectLeads	boolean	Optional	Ask visitors for contact details.
settings.leadCaptureMode	string one of `before_chat` · `after_first_response` · `on_handoff` · `manual`	Optional	When the lead form appears.
settings.suggestedQuestions	array up to 10 items	Optional	Starter questions shown to visitors.
settings.placeholderText	string up to 120 chars	Optional	Input placeholder.
settings.avatarUrl	string up to 2000 chars, or null	Optional	Bot avatar URL.
settings.proactiveEnabled	boolean	Optional	Open the widget proactively.
settings.proactiveMessage	string up to 300 chars, or null	Optional	Proactive greeting.
settings.proactiveDelaySeconds	integer 0–600	Optional	Delay before the proactive open.
settings.aiDisclosureEnabled	boolean	Optional	Show the AI-disclosure notice.
settings.aiDisclosureText	string up to 300 chars, or null	Optional	AI-disclosure text.

Request

curl

curl -X PUT "https://app.evoriqa.com/api/v1/chatbots/{chatbotId}/appearance" \
  -H "x-api-key: $EVORIQA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatbot": { "botName": "Ava", "greetingMessage": "Hi! How can I help?" }, "settings": { "position": "bottom-right", "primaryColor": "#4373fc" } }'

Node.js

const res = await fetch("https://app.evoriqa.com/api/v1/chatbots/{chatbotId}/appearance", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.EVORIQA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "chatbot": {
      "botName": "Ava",
      "greetingMessage": "Hi! How can I help?"
    },
    "settings": {
      "position": "bottom-right",
      "primaryColor": "#4373fc"
    }
  }),
});

const responseBody = await res.json();

Python

import os
import requests

res = requests.put(
    "https://app.evoriqa.com/api/v1/chatbots/{chatbotId}/appearance",
    headers={"Authorization": f"Bearer {os.environ['EVORIQA_API_KEY']}"},
    json={
      "chatbot": {
        "botName": "Ava",
        "greetingMessage": "Hi! How can I help?"
      },
      "settings": {
        "position": "bottom-right",
        "primaryColor": "#4373fc"
      }
    },
)

body = res.json()

Response

200 OK

{
  "success": true,
  "data": {
    "chatbot": {
      "botName": "Ava",
      "greetingMessage": "Hi! How can I help?"
    },
    "settings": {
      "primaryColor": "#4373fc",
      "position": "bottom-right",
      "showPoweredBy": true,
      "collectLeads": true,
      "leadCaptureMode": "on_handoff",
      "suggestedQuestions": [
        "What does it cost?",
        "How do I get started?"
      ],
      "placeholderText": "Ask a question...",
      "proactiveEnabled": false,
      "aiDisclosureEnabled": true
    }
  }
}