Update Chat Widget Appearance via API

Update Chat Widget Appearance via API

Use this endpoint to programmatically customize how your chat widget looks and behaves for a specific Chat Agent.

Overview

You can update the chat widget appearance by sending a PUT request with your desired settings. This lets you control colors, fonts, images, borders, and various UI behaviors without using the dashboard.

Endpoint

PUT https://app.floraai.me/en/chatbot/api/v1/chatwidget/{chatbot_uuid}/appearance/update/

Replace:

• {chatbot_uuid} with the UUID of the chatbot whose widget appearance you want to update.

Authentication & Headers

Include the following headers in every request:

Content-Type: application/jsonAuthorization: Token <Your-API-Token>

• Content-Type must be application/json when sending JSON.

• Authorization must contain a valid API token.

Note: Image fields are listed as ImageField. In practice, these are usually handled as URLs or via multipart uploads depending on your integration. If your environment requires file uploads, use multipart/form-data instead of JSON and adjust accordingly.

Request Body Parameters

All parameters are optional unless marked as Required. You can send only the fields you want to change; others will remain unchanged.

Chat Bubble & Avatars

• chat_bubble_img (ImageField, Optional)
  Image used for the chat bubble icon (launcher button).

• chat_bubble_color (CharField, Optional)
  Color of the chat bubble (e.g., #0000FF or rgb(0,0,255)).

• chat_avatar_image (ImageField, Optional)
  Image shown as the chatbot’s avatar at the start of the conversation.

• user_msg_avatar_image (ImageField, Optional)
  Image shown as the user’s avatar next to their messages.

• icon (ImageField, Optional)
  Icon for the chat widget (often used in the launcher or header).

• send_msg_button_image (ImageField, Optional)
  Custom image for the send message button. If omitted, a default icon is used.

Background & Header

• widget_bg_image (ImageField, Optional)
  Background image for the chat widget when using an image background.

• widget_header_banner_image (ImageField, Optional)
  Image displayed as a banner in the widget header.

• header_gradient_color_1 (CharField, Optional)
  First color of the header gradient.

• header_gradient_color_2 (CharField, Optional)
  Second color of the header gradient.

• widget_bg_preference (ChoiceField, Optional)
  How the widget background is displayed. Typical values:

• "color" – use a solid color

• "image" – use a background image

• widget_bg_color (CharField, Optional)
  Background color of the widget when "color" is selected as the background preference.

Typography

• font_family (ChoiceField, Optional)
  Font family for chat text (e.g., "system-ui", "Arial", "Roboto").
  Available options depend on your platform configuration.

• font_size (IntegerField, Optional)
  Base font size in pixels (e.g., 16).

Message Bubbles & Text Colors

• user_message_bg_color (CharField, Optional)
  Background color of user message bubbles.

• user_msg_text_color (CharField, Required)
  Text color inside user message bubbles.

• ai_message_bg_color (CharField, Optional)
  Background color of AI (agent) message bubbles.

• ai_msg_text_color (CharField, Required)
  Text color inside AI message bubbles.

Widget Text & Tagline

• subheading (CharField, Optional)
  Subheading text displayed under the chatbot name in the header.

• show_tagline (BooleanField, Optional)
  Whether to display the tagline in the widget (true or false).

• tagline (CharField, Optional)
  Tagline text, e.g., "Powered by Your Brand".

• chatwidget_title_text_color (CharField, Optional)
  Color of the chat widget title text in the header.

• tagline_color (CharField, Optional, may be present in responses)
  Color of the tagline text (if supported in your configuration).

Typing Simulation

• enable_response_typing_simulation (BooleanField, Optional)
  If true, the widget simulates typing when the AI is generating a response.

• response_typing_speed (IntegerField, Optional)
  Speed of the typing simulation. Higher or lower values may correspond to faster or slower typing, depending on implementation.

Borders & Layout

• widget_border_width (IntegerField, Optional)
  Border thickness of the widget in pixels (e.g., 1, 2).

• widget_border_color (CharField, Optional)
  Color of the widget border.

• size_of_widget (Optional, appears in responses)
  Overall size of the widget (e.g., "small", "medium", "large"), if supported.

Input Field & Hyperlinks

• chat_input_placeholder (CharField, Optional)
  Placeholder text in the message input box (e.g., "Type your message...").

• chat_input_text_color (CharField, Optional)
  Text color inside the input field.

• widget_input_bg_color (CharField, Optional)
  Background color of the input field.

• hyperlink_color (CharField, Optional)
  Color used for hyperlinks in messages.

AI Agent Status Messages

• enable_ai_agent_status_messages (BooleanField, Optional)
  If true, shows rotating status messages for the Chat Agent (e.g., “Online”, “Typing…”).

• ai_agent_status_messages (CharField, Optional)
  Status messages separated by new lines.
  Example:

  Online  Typing...  Away

• use_icon_image_as_avatar (BooleanField, Optional, may be present in responses)
  If true, the widget may use the icon image as the avatar.

Example Request (Python)

Below is a basic example using requests with JSON. Adjust the url to include your chatbot_uuid and replace placeholder values with real ones.

import requestschatbot_uuid = "<YOUR-CHATBOT-UUID>"# Define the API endpointurl = f"https://app.floraai.me/en/chatbot/api/v1/chatwidget/{chatbot_uuid}/appearance/update/"# Set up authentication and headersheaders = {    "Authorization": "Token <YOUR-API-TOKEN>",    "Content-Type": "application/json",    "Accept": "application/json",}# Data is passed in the request body as JSONdata = {    "chat_bubble_color": "#0000FF",    "header_gradient_color_1": "#0061f2",    "header_gradient_color_2": "#d9dbdf",    "font_family": "system-ui",    "font_size": 16,    "widget_bg_preference": "color",    "widget_bg_color": "#fafafa",    "user_message_bg_color": "#DAE7FB",    "ai_message_bg_color": "#E0E5EC",    "user_msg_text_color": "#222222",    "ai_msg_text_color": "#222222",    "subheading": "How can I help you today?",    "show_tagline": True,    "tagline": "Powered by Your Brand",    "enable_response_typing_simulation": True,    "response_typing_speed": 10,    "widget_border_width": 1,    "widget_border_color": "#e0e5ec",    "chat_input_placeholder": "Type your message...",    "chatwidget_title_text_color": "#FFFFFF",    "chat_input_text_color": "#222222",    "hyperlink_color": "#0964f1",    "widget_input_bg_color": "#fafafa",    "enable_ai_agent_status_messages": True,    "ai_agent_status_messages": "Online\nTyping...",}response = requests.put(url, headers=headers, json=data)# Process the responseif response.status_code in (200, 201, 202):    result = response.json()    print("Response data:", result)else:    try:        error_data = response.json()        error_message = error_data.get("message") or error_data.get("error", "Unknown error")        print(f"Error: {error_message}")    except ValueError:        print(f"Error: Status code {response.status_code}")

If you need to upload actual image files instead of URLs or existing references, use multipart/form-data and the files parameter in requests instead of json=data.

Example Response

A successful response returns the updated appearance configuration:

{  "chat_bubble_img": "https://example.com/chat-bubble.png",  "chat_bubble_color": "#0000FF",  "chat_avatar_image": "https://example.com/chat-avatar.png",  "user_msg_avatar_image": "https://example.com/user-msg-avatar.png",  "icon": "https://example.com/icon.png",  "send_msg_button_image": "https://example.com/send.png",  "widget_bg_image": "https://example.com/widget-bg.png",  "widget_header_banner_image": "https://example.com/widget-header-banner.png",  "header_gradient_color_1": "#0061f2",  "header_gradient_color_2": "#d9dbdf",  "font_family": "system-ui",  "font_size": 16,  "widget_bg_color": "#fafafa",  "user_message_bg_color": "#DAE7FB",  "ai_message_bg_color": "#E0E5EC",  "subheading": "How can I help you today?",  "tagline": "Powered by Stammer",  "enable_response_typing_simulation": true,  "response_typing_speed": 10,  "widget_border_width": 1,  "size_of_widget": "medium",  "chatwidget_title_text_color": "#FFFFFF",  "user_msg_text_color": "#222222",  "ai_msg_text_color": "#222222",  "chat_input_text_color": "#222222",  "widget_border_color": "#e0e5ec",  "widget_input_bg_color": "#fafafa",  "hyperlink_color": "#0964f1",  "show_tagline": true,  "tagline_color": "#d9dbdf",  "chat_input_placeholder": "Type your message...",  "widget_bg_preference": "color",  "enable_ai_agent_status_messages": true,  "ai_agent_status_messages": "Online\nTyping...",  "use_icon_image_as_avatar": false}

Use this response to confirm that your settings were applied correctly or to store the current configuration for future reference.