The Embeddable Widget APIs allow you to programmatically control and customize the behaviour of a help widget or embedded form on your website. For example, you can hide the default launcher, open the widget from a custom button, prefill form fields, or display a specific knowledge base article.

Supported actions
You can use the Embeddable Widget APIs to perform the following actions:

• Hide launcher button
• Show launcher button
• Open the widget
• Close the widget
• Prefill form fields
• Open an article
• Set user Identity Token

Prerequisites

Before using the APIs, ensure that:

• The widget or web form is configured.
• The widget embed code is added to your website.
• API calls are made after the widget is initialised.
• Page-load configuration is placed above the widget embed code.
• The field API names, field values, option IDs, and article IDs used in the code match those configured in your account.

Hide the launcher button

If your website already has a custom button or link for opening the help widget, you can hide the default launcher button.

BolddeskWidget('hide', 'launcher');

This is useful when you want customers to open the widget only through a custom website control, such as Contact Us, Help, or Get Support.

Show the launcher button

Use the following API to show a launcher button that was previously hidden:

BolddeskWidget('show', 'launcher');

This API can be used when the visibility of the launcher depends on the page, customer action, or another condition in your website.

Open the Widget

Use the following API to open the help widget as a popup:

BolddeskWidget('open', 'popup');

You can call this API when a customer selects a custom button or link on your website.

To learn more on how to open the widget pop-up on the external button/link, explore How to launch the BoldDesk Help Widget on Button Click.

Automatically Open the Widget

If you want to automatically open the widget when a customer visits your website, you can use the API below.

 window.BolddeskWidgetConfig = {
     created: (args) => {
       BolddeskWidget('open', 'popup');
     }
 }

Close the Widget

If the widget is already open, use this API to close it.

BolddeskWidget('close', 'popup');

Prefill Form Fields

To fill out the form (such as name, email), use the prefill API. For dropdown options (single or multi-select), assign the provided ID as the value. For other fields, assign a string value.

BolddeskWidget('fill', 'form', {
  name: 'Daniel',
  emailId: '[email protected]',
  categoryId: 12,
  cf_country: 21,
  cf_state: 17
});

Open an Article

You can use this API to open an article when customers click a link on your website. Make sure to include the article ID when using the API.

BolddeskWidget('open', 'article', {
 id: 123 // article ID
});

Onload Customisation

Add the following script above the embedded code to hide the launcher and pre-fill the form fields (such as name, email) when the page loads.

<script>
window.BolddeskWidgetConfig = {
   widget: {
       hideLauncher: true
   },
   form: {
       fill: {name: "Daniel", emailId: "[email protected]", categoryId: 12 }
   },
   created: (args) => {
       // When the widget is rendered, the created event will be triggered.
   }
}
</script>

When a widget is rendered, the created event will be triggered. The following properties can be found in the created event argument.

{
     type: 'widget',
     id: 'Widget Id',
     name: 'Widget Name'
}

Frequently Asked Questions

1. What can I do with the Embeddable Widget JavaScript APIs?
   You can use the APIs to control supported widget and form behaviour from your website. Common actions include:

   • Hiding or showing the launcher
   • Opening or closing the widget
   • Prefilling supported form fields
   • Opening a specific knowledge base article
   • Running an action after the widget or form is initialised

   The available actions may vary depending on whether you are using a help widget or an embedded web form.

2. Can I hide the launcher without disabling the widget?
   Yes. Hiding the launcher removes the default launcher from the page, but the widget remains available through JavaScript.

3. How do I prefill name and email fields?
   Use the fill action with the form target:

BolddeskWidget('fill', 'form', {
 name: 'Daniel',
 emailId: '[email protected]'
}); 

Make sure the property names match the supported field API names.

4. What happens if I provide an invalid article ID?
   The article may not open, or the widget may display an unavailable-content response. Confirm that:
   • The article exists.
   • The article is published.
   • The article is available to the intended audience.
   • The article ID is correct.
   • The article belongs to the knowledge base associated with the widget.

Related Article

1. Live Chat Widget JavaScript API Guide
2. How to Locate the Open API Definition for BoldDesk Rest APIs