Widget Tools | Yaplet

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, getting install codes, and linking them to chatbots and knowledge bases.

Permission required:Copilot.Widgets

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

Parameter	Type	Required	Description
`id`	string	No	Widget ID. Omit to create a new widget, provide to update.
`isDefault`	boolean	No	Only for creation — links default KB, roadmap, and docs to the new widget.
`name`	string	No	Display name for the widget.
`language`	string	No	Widget language: `"en"` or `"hu"`.
`replyTime`	string	No	Expected reply time shown to visitors (e.g., `"a few minutes"`, `"in a few hours"`).
`feedbackButtonPosition`	string	No	Launcher position: `"BOTTOM_RIGHT"` or `"BOTTOM_LEFT"`.
`buttonIcon`	string	No	Launcher icon style: `"button"` (message bubble) or `"button-2"` (AI icon).
`backgroundType`	string	No	Home screen decoration: `"decoration"`, `"decoration_blobs"`, `"decoration_lighting"`, `"decoration_gradient"`, `"decoration_ripple"`, `"decoration_grid"`, `"full_image"`, `"small_image"`, or `"none"`.
`hideBranding`	boolean	No	Hide Yaplet branding in the widget.
`showTeam`	boolean	No	Show team member avatars in the widget.
`askForEmail`	boolean	No	Ask visitors for their email address.
`collectRating`	boolean	No	Ask for a conversation rating when the chat ends.
`askForRatingLabel`	string	No	Custom text for the rating prompt.
`menus`	object	No	Navigation menu configuration. Each key (`home`, `messages`, `news`, `roadmap`, `help`) can have `show` (boolean) and `title` (string).
`generalBackground`	string	No	Main chat background hex color (e.g., `"#FFFFFF"`). Sub-colors are auto-generated.
`generalAccent`	string	No	Primary accent/UI hex color (e.g., `"#083BD9"`). Sub-colors are auto-generated.
`homeTopBackground`	string	No	Home screen top/header background hex color.
`homeBackground`	string	No	Home screen body background hex color.
`homeHighlightLeft`	string	No	Home decoration left accent hex color.
`homeHighlightRight`	string	No	Home decoration right accent hex color.

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.
Use isDefault: true to automatically link the organization's default knowledge base, documentation, and roadmap.

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.

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."
"Move the launcher button to the bottom left."
"Rename my widget to 'Customer Portal'."

get_widget_install_code

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

Parameters

Parameter	Type	Required	Description
`widgetId`	string	Yes	The 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, or roadmap to a widget.

Parameters

Parameter	Type	Required	Description
`widgetId`	string	Yes	The widget to link to.
`type`	string	Yes	What to link: `"chatbot"`, `"knowledgebase"`, `"documentation"`, or `"roadmap"`.
`id`	string or null	Yes	ID of the resource to link. Pass `null` to unlink.

How It Works

Chatbot linking:

Links the chatbot to the widget so it can respond to visitors.
Pass id: null to unlink the chatbot from the widget.

Knowledge base / Documentation / Roadmap linking:

Updates the widget's linked resource.
When you change a linked knowledge base or documentation, old AI training data is automatically cleaned up.
The response will note if training data needs to be refreshed (this happens from the dashboard widget settings).

Example Prompts

"Link my Support Bot chatbot to my default widget." (finds both resources first, then links them)
"Connect my Help Center knowledge base to the widget."
"Unlink the chatbot from my widget."
"Switch the knowledge base on my widget to the new one I just created."
"Link the documentation and roadmap to my default widget."

Common Workflow Patterns

Full Widget Setup

A complete widget setup typically involves:

Create the widget → manage_widget
Customize appearance → manage_widget (update with colors, menus, etc.)
Link a chatbot → link_to_widget with type: "chatbot"
Link a knowledge base → link_to_widget with type: "knowledgebase"
Get the install code → get_widget_install_code

Example prompt: "Set up a complete widget: create one called 'Support Chat' with a blue theme, link my AI chatbot to it, connect my knowledge base, 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."