Documentation

Widget Tools

Widget tools let you create and customize your chat widgets — appearance, colors, navigation menus and behavior settings — and get the install code for your website.

Overview

Widgets are the customer-facing chat interfaces that you embed on your website. The Widget tool category gives you full control over creating new widgets, customizing their appearance and behavior, and getting install codes.

Permission required:Brands — shown as Brands & chat widgets in the permission list.

manage_widget

Creates a new widget or updates an existing one. This is a powerful tool that handles everything from naming to full theme customization.

Parameters

ParameterTypeRequiredDescription
idstringNoWidget ID. Omit to create a new widget, provide to update.
namestringNoDisplay name for the widget.
languagestringNoWidget interface language: "en" or "hu".
replyTimestringNoExpected reply time shown to visitors (e.g., "a few minutes", "in a few hours").
feedbackButtonPositionstringNoLauncher position: "BOTTOM_RIGHT" or "BOTTOM_LEFT".
buttonIconstringNoLauncher icon style: "button" (message bubble) or "button-2" (AI icon).
backgroundTypestringNoHome screen decoration: "decoration", "decoration_blobs", "decoration_lighting", "decoration_gradient", "decoration_ripple", "decoration_grid", "full_image", "small_image", or "none".
showTeambooleanNoShow team member avatars in the widget.
askForEmailbooleanNoAsk visitors for their email address.
collectRatingbooleanNoAsk for a conversation rating when the chat ends.
askForRatingLabelstringNoCustom text for the rating prompt.
menusobjectNoNavigation menu configuration. Each key (home, messages, news, roadmap, help) can have show (boolean) and title (string).
generalBackgroundstringNoMain chat background hex color (e.g., "#FFFFFF"). Sub-colors are auto-generated.
generalAccentstringNoPrimary accent/UI hex color (e.g., "#083BD9"). Sub-colors are auto-generated.
homeTopBackgroundstringNoHome screen top/header background hex color.
homeBackgroundstringNoHome screen body background hex color.
homeHighlightLeftstringNoHome decoration left accent hex color.
homeHighlightRightstringNoHome decoration right accent hex color.
feedbackButtonStopsarrayNoLauncher button colors, 1–3 hex values. One entry is a solid color; two or three make a linear gradient. The first entry is the primary color.
feedbackButtonAnglenumberNoGradient angle in degrees (0–360). Ignored with a single color stop. Defaults to 90.
feedbackButtonIconColorstringNoHex color for the launcher icon. Derived automatically from contrast if omitted.

How It Works

Creating a widget:

  • Omit the id parameter. A new widget is created with default settings.
  • You can immediately customize it by passing additional parameters alongside the creation.
  • A new brand is created to hold the widget. That brand starts empty — it does not inherit your existing knowledge base, documentation or roadmap. If you meant to restyle the widget you already have, pass its id instead.

Updating a widget:

  • Provide the id of the widget to update. Only the fields you pass will be changed — everything else stays the same.
  • Menu updates are merged: if you only change news.show, all other menu settings remain unchanged.

Color system:

  • You only need to set the main colors (generalBackground, generalAccent for chat; homeTopBackground, homeBackground, homeHighlightLeft, homeHighlightRight for the home screen).
  • All derived sub-colors (text colors, border shades, bubble colors, etc.) are automatically generated from these main colors.
About language. The widget designer no longer shows a language picker — language is chosen on Brand settings → General, and saving it there writes the value down onto the widget. language here writes that same widget-level value directly, so the change takes effect immediately, but the brand still holds its own copy: the next time anyone saves the brand's language, the brand's value wins and overwrites yours. For a lasting change, set it on the brand.

Example Prompts

  • "Create a new widget."
  • "Create a widget called 'Premium Support' with a dark blue accent color."
  • "Change my widget's theme to use #1A1A2E background and #E94560 accent."
  • "Hide the news and roadmap tabs from my widget."
  • "Set my widget to collect conversation ratings with the message 'How did we do?'"
  • "Enable the 'ask for email' setting on my default widget."
  • "Change the home screen background to a gradient decoration with warm colors."
  • "Make the launcher a gradient from #6C63FF to #FF6B6B at 45 degrees."
  • "Rename my widget to 'Customer Portal'."

get_widget_install_code

Generates the JavaScript snippet needed to install a widget on your website.

Parameters

ParameterTypeRequiredDescription
widgetIdstringYesThe ID of the widget to get the install code for.

How It Works

Returns the widget's details along with a ready-to-use <script> tag that you can paste into your website's HTML. The script loads the Yaplet widget asynchronously and won't slow down your page.

Example Prompts

  • "Give me the install code for my default widget." (lists widgets first to find the default, then gets the code)
  • "How do I install the Premium Support widget on my website?"
  • "Generate the embed script for my widget."

link_to_widget

Links or unlinks a chatbot, knowledge base, documentation set, or roadmap board to a widget.

You almost certainly don't need this. A brand has at most one AI agent and it answers on that brand's chat widget automatically, and which knowledge base and documentation set a brand serves is chosen on Brand → Knowledge. The tool still exists and still works, but it writes the brand's setting — it is not a second, competing one. What went away is the widget designer's Connections section, not the choice itself.

Parameters

ParameterTypeRequiredDescription
widgetIdstringYesThe widget to link to.
typestringYesWhat to link: "chatbot", "knowledgebase", "documentation", or "roadmap".
idstring or nullYesID of the resource to link. Pass null to unlink.

How It Works

Chatbot linking:

  • Sets the widget's AI agent. Only a chatbot of type AI is accepted — a chat workflow cannot be put in this slot, and the tool refuses it with an explanation.
  • The same choice is written onto the widget's brand, which is what the AI actually reads from.
  • Pass id: null to clear the widget's AI agent. This is not the inverse of the step above: it takes the bot off the widget only. The brand keeps its Vex agent and it still appears on Brand → Vex, and the brand's chat workflows are left alone.

Knowledge base / Documentation / Roadmap linking:

  • Updates the widget's linked resource, and — for a knowledge base or documentation set — writes the same choice onto the widget's brand, which is what the AI and the public help site actually read from.
  • Nothing is deleted and nothing is re-processed. Everything a source has learnt belongs to that source, not to whichever widget happens to display it, so re-attaching it later is instant and free.
  • It is not invisible, though. Linking a knowledge base or documentation set also makes it the one served at the brand's public web address, which takes the previous one off that address; passing id: null leaves the brand publishing nothing there.
  • The response still carries training_data_cleared and training_data_needs_refresh flags and a note about refreshing training data from the widget settings. That wording is left over from the old behaviour — ignore it. No indexed content is removed and there is nothing to refresh.

Example Prompts

  • "Connect my Support knowledge base to the widget."
  • "Switch the knowledge base on my widget to the new one I just created."
  • "Link the documentation and roadmap to my default widget."
  • "Which knowledge base is my widget currently serving?"
  • "Clear the roadmap link on my widget."

Common Workflow Patterns

Full Widget Setup

A complete widget setup typically involves:

  1. Create the widget → manage_widget
  2. Customize appearance → manage_widget (update with colors, menus, etc.)
  3. Get the install code → get_widget_install_code

Example prompt: "Set up a complete widget: create one called 'Support Chat' with a blue theme, and give me the install code."

Theme Customization

You can do complete visual overhauls in a single call:

Example prompt: "Give my widget a dark theme with #0F0F23 background, #6C63FF accent, and a gradient decoration on the home screen with #1A1A2E top background and #6C63FF / #FF6B6B highlights."