The BoldDesk web widget allows customers to search knowledge base articles, interact with an AI agent, and submit support tickets without leaving your website. This article explains how to create and configure a web widget, copy the embed code, add the widget to an external website, and verify that the widget works correctly.

Tickets submitted through the widget are created in BoldDesk and become available to support agents in the agent portal. Depending on the applicable customer portal access and authentication settings, customers may also be able to access their submitted tickets through the customer portal.

Check out this video to learn more about embeddable widgets.

Prerequisites

Before creating and embedding a web widget, make sure that:

• Your role has the Manage settings permission.
• You know which brand the widget should use.
• The selected brand has the required ticket fields and customer portal settings.
• You have permission to edit the HTML or shared layout of the external website.
• The knowledge base is enabled for the selected brand if you want articles to appear in the widget.
• The external website allows the BoldDesk embed script to load.

Create a web widget

To add a new widget, follow these steps:

1. Navigate to Admin → under Channels → select Web Widgets & AI Agent.

2. Click the Add Widget button on the right side.
   

   
   
   

3. In the Name and Brand section:

   • Widget Name: Enter a descriptive name that helps administrators identify where or how the widget is used. This field is required.

   • Brand: Select the brand whose settings and customer-facing identity the widget should use. This field is required.

   • Auto Tag Ticket: Select one or more tags to apply automatically to tickets created through this widget. This field is optional.
     

     
     
     

4. Configure the following sections as required:

   • Widget Customization
   • Launcher Button Customization
   • Contact Form
   • Knowledge Base
   • AI Agent Configuration
   • Advanced Customization, if available

5. Click Add to create the widget. When editing an existing widget, click Update instead.

After the widget is created successfully, BoldDesk displays the embed code in a dialog. The widget also appears in the Active widgets list, where the embed code can be accessed later.

Widget customization

Use the Widget Customization section to configure the appearance of the widget header.

• Logo – Enable or disable the logo in the widget header. When enabled, the default logo configured for the selected brand is displayed. You can also upload a different logo for the widget.
• Header Text – Enter the primary text displayed in the widget header.
• Header Description – Enter the supporting text displayed below the header text.
• Header Theme Color – Select the background color used in the widget header.

The preview reflects the selected logo, text, description, and theme color.

Launcher button customization

Use the Launcher Button Customization section to control the appearance and location of the button that opens the web widget.
The following options are available:

• Button Text – Enter the text displayed on the launcher button.

• Position – Choose whether the launcher appears in the bottom-left or bottom-right corner of the page.

• Offset – Set the launcher’s distance from the applicable left or right edge and from the bottom of the page.

• Background Color – Select the launcher button’s background color.

• Text Color – Select the color of the launcher button text.
  

  
  
  

Contact form customization

Use the Contact Form section to configure how customers submit tickets through the widget.

Select a form option

The Form Option field provides the following choices:

• Contact form: Displays the standard fields, such as Name, Email, Phone Number, Subject, and Description.
• Contact form with ticket fields: Displays the standard contact fields together with eligible system and custom ticket fields associated with the selected brand.

Customize the form content

Configure the following text displayed in the form:

• Form Title: The title displayed at the top of the contact form.

• Form Description: Supporting text displayed below the form title.

• Footer Message: Text displayed in the form footer.

• Confirmation Message: The message displayed after a ticket is submitted successfully.

• Submit Button Text: The text displayed on the form submission button.
  

  
  
  

Configure additional form options

You can also enable or disable the following options:

• GDPR Consent: Requires the customer to provide the configured consent before submitting the form.

• File Attachments: Allows customers to attach files to the ticket. When enabled, a customer can attach up to five files.

• Google reCAPTCHA: Helps prevent automated and spam submissions.
  

  
  
  

Advanced customization

If Advanced Customization is available, you can add:

• Custom CSS to override supported default widget styles.

• Custom JavaScript to implement supported custom behavior.
  

  
  
  

Knowledge base customization

Use the Knowledge Base section to make selected knowledge base content available inside the web widget.
The following options are available:

• Enable Knowledge Base: Enables knowledge base content in the widget.

• Header Text: Sets the title displayed in the widget’s knowledge base section.

• Category: Determines which knowledge base categories are available in the widget.
  

  
  
  

Before enabling this option, make sure that the knowledge base is enabled for the selected brand in the customer portal settings. The same brand must be selected in the web widget. Only categories visible to all users are available in the category selection field.

AI Agent Configuration

Use the Enable AI Agent section to make an AI-powered support agent available through the web widget. The AI Agent can answer customer questions using the knowledge sources configured for the selected AI Agent, helping customers find relevant information before submitting a support ticket.
To configure an AI Agent for the widget, follow these steps:

1. Turn on the Enable AI Agent toggle.

2. Under Choose AI Agent Experience, select one of the following options:

   • AI Agent 2.0: Provides the enhanced AI experience with improved responses and advanced capabilities.
   • Classic AI Agent: Uses the existing AI Agent behavior and current setup.

3. From the required Select AI Agent dropdown, choose the AI Agent that should be connected to the web widget.

4. Click Add to create the widget. When editing an existing widget, click Update instead.
   

   
   
   

Copy the embed code

After the widget is created or updated successfully, BoldDesk displays the embed code in a dialog.
To copy the code immediately:

1. Locate the embed code in the confirmation dialog.

2. Click Copy.

3. Store the code temporarily in a secure text editor or paste it directly into the website template.
   

   
   
   

You can also copy the code later from the widget list:

1. Go to Admin → Channels → Web Widgets & AI Agent.

2. Locate the required widget.

3. Open the widget’s More options menu.

4. Select the embed-code option.

5. Click Copy.
   

   
   
   

Add the web widget to an external website

After copying the embed code, add it to the external website.

1. Open the website’s HTML file, shared layout, theme, tag manager, or custom-code editor.
2. Determine where the widget should be available:
   • Site-wide: Add the code to a shared website template or global custom-code area.
   • Selected pages: Add the code only to the required page templates or use the website platform’s page-targeting options.
3. Paste the complete embed code before the closing tag, unless the website platform requires scripts to be added in a designated custom-code area.
4. Save the changes.
5. Publish or deploy the updated website.

Platform-specific placement

Depending on the website platform, you may need to add the embed code through:

• A global footer or custom-code area
• A shared layout or theme file
• A tag-management tool
• A content management system extension or plug-in
• A page builder’s custom HTML or custom script component

If the widget should appear on every page, add the code to a global or shared template. If the widget should appear only on selected pages, add the code only to those pages or use the platform’s page-targeting controls.

Ticket history properties

By using the ticket history properties, you can identify the site through which the user made contact. On the ticket history tab, you can find two properties.

• Source: Widget name will be displayed if you have created multiple widgets.

• Source Site URL: If it is possible to fetch, it will retrieve the web page URL where the widget is hosted.
  

  
  
  

Permission required to create a widget

For creating a new widget, you should enable the Manage settings permission.

Troubleshooting

The launcher button does not appear

• Confirm that the widget is active.
• Confirm that the complete embed code was copied.
• Make sure the embed code is present in the published version of the website.
• Check whether the browser blocked the BoldDesk script.
• Review the website’s Content Security Policy.
• Check whether another fixed element is covering the launcher button.
• Open the website in a private browsing window and test it again.
• Clear the website and browser cache after publishing an updated template.

The widget opens, but the contact form is unavailable

• Confirm that the contact form is enabled in the widget configuration.
• Confirm that the selected brand has the appropriate customer portal and ticket settings.
• Review any custom JavaScript that could affect the widget behavior.
• Confirm that the latest widget configuration was saved.

Ticket fields are missing

• Confirm that Contact form with ticket fields is selected.
• Confirm that the fields are associated with the selected brand.
• Confirm that the fields are configured as visible in the customer portal.
• Review the applicable field dependencies.
• Review the field display conditions.

The widget works on some pages but not others

• Confirm that the embed code is included in the shared template used by all required pages.
• Compare the source code of a working page with the source code of an affected page.
• Check whether page-specific security policies block the widget script.
• Confirm that the affected page does not contain conflicting JavaScript.
• Review page-targeting rules if the embed code was added through a tag manager.

Frequently asked questions

1. Can I use the same web widget on multiple websites?
   Yes, you can use the same BoldDesk web widget on multiple websites by embedding its script on each site.

2. Can I display the web widget only on selected pages or to specific visitors?
   You can control page-level placement by adding the embed code only to selected pages or by using the targeting features available in your website platform or tag manager.

3. Can the web widget be translated into multiple languages?
   Yes. BoldDesk supports translating/displaying web widgets in multiple languages, and the same widget can be embedded in different languages by using different language codes in the embed script URL.

4. Can customers view ticket updates directly inside the web widget?
   No, customers cannot view ticket updates directly inside the BoldDesk web widget.

Related Articles

1. How to Enable an AI Agent in BoldDesk’s Web Widget.
2. Embedding Web Widgets in BoldDesk Customer Portal Using Custom JS.