Widget Client SDK

Important
Improperly applying customizations with the widget client SDK can impact the Wix Answers widget experience.
The Widget Client SDK enables you to add JavaScript code to customize a Wix Answers widget that appears on your page (see Installing a Widget on Your Website), including the widget icon, tooltip, and badge, general screen appearance, user authentication, and chat. You use this SDK by adding JavaScript on the page on which the widget appears, after the widget is loaded: add the relevant JavaScript to the callback function sent as a parameter to AnswersWidget.onLoaded.

You can test the code in your browser console before entering it on your page.

The SDK enables you to access various events, such as chat started or ended, and receive the relevant info to add custom functionality.
Note
If you have specific integration needs not met using the existing SDK, contact us at help@wixanswers.com with your request.

Methods By Subject

Method
Description
Page Interaction

Execute a callback when the widget is loaded.

This is the only method available before the widget is loaded. Add all of your other code to the listener configured for this function.
Display the widget.
Hide the widget.
Set the location of the widget on the page, relative to the widget's initial X and Y position.
Execute a callback function immediately after the user finishes dragging the widget.
Open the widget screen.
Execute a callback when the widget screen is opened.
Close the widget screen.
Execute a callback when the widget screen is closed.
Destroy the widget.
Icon and Tooltip Config

Set the launcher icon to the passed SVG content string.
Set the contents and delay of the widget tooltip that appears when the page with the widget is first loaded.
Execute a callback when the tooltip is closed.
Configure the tooltip background, and whether to show the tooltip even when there are no unread messages.
Widget Config

Add HTML to the end of header of the widget home page.
Add HTML to the end of header of every category, article list, and article pages.
Display only the featured articles that match a search term.
Set the labels that are automatically added to all new tickets, chats, and callbacks.
Eject the widget view from a DOM element, by ID.
Inject the widget view into a DOM element.
Set custom fields for a chat, ticket, or callback.
Override texts in the widget.
Authentication and Initial Contents

Add an authentication function (make this an authenticated widget).
Prefill the email contact form with contents.
Set the user's email address, for chat, email, or callbacks.
Open an article in the widget screen.
Open a category in the widget screen.
Open the callback contact form in the widget screen.
Open the chat contact form in the widget screen.
Open the email contact form in the widget screen.
Chat Config

Get whether the user started a chat that was not finished and closed.
Execute a callback when a chat message is received.
Execute a callback when a chat message is sent.
Execute a callback when a chat starts.
Add a "bot message" to a chat.

Methods Reference

AnswersWidget.addHtmlToHomePageHeader(HTML:string)

Add HTML to the end of header of the widget home page.

Returns: None

For example, the following shows a home page with an embedded SVG file.
1
AnswersWidget.addHtmlToHomePageHeader(html);

AnswersWidget.addHtmlToKbHeader(HTML:string)

Add HTML to the end of header of every category, article list, and article pages.

Returns: None

For example, the following shows a page with a custom header.
1
AnswersWidget.addHtmlToKbHeader(html);

AnswersWidget.addAuthenticationFn(authFn:function)

Add an authentication function. The function is called with no arguments and must return a Promise that resolves to a token string.

To learn about authenticated widgets see here.

Returns: None
1
AnswersWidget.addAuthenticationFn(authenticationFunction);

AnswersWidget.close()

Close the widget screen.

Returns: None
1
AnswersWidget.close()

AnswersWidget.destroy()

Destroy the widget.

Returns: None
1
AnswersWidget.destroy()

AnswersWidget.ejectFromElementById(DOM-ID:string)

Eject the widget view from a DOM element, by ID.

Returns: None
1
AnswersWidget.ejectFromElementById(DOM_ELEMENT_ID)

AnswersWidget.featuredArticlesSearch(searchTerm:string)

Display only the featured articles that match the search term. You configure featured articles in the Wix Answers app when configuring the widget. This method enables you to display relevant articles only, based on the page topic (for example).

Returns: None
1
2
3
4
5
AnswersWidget.featuredArticlesSearch(searchTerm)

// For example

AnswersWidget.featuredArticlesSearch("electronics")

AnswersWidget.fillContactForm({subject: subject:string, description: description:string})

Prepopulate the email contact form with a subject and/or description. Also see AnswersWidget.goToContact.

Returns: None
1
2
3
4
5
AnswersWidget.fillContactForm({subject: subject, description: description})

// For example

AnswersWidget.fillContactForm({subject: 'This is the subject', description: 'This is description'})

AnswersWidget.goToArticle(article:GUID)

Open an article in the widget screen.

Returns: None
1
AnswersWidget.goToArticle(ARTICLE_ID)

AnswersWidget.goToCallback()

Open the callback contact form in the widget screen.

Returns: None
1
AnswersWidget.goToCallback()

AnswersWidget.goToCategory(category:GUID)

Open a category in the widget screen.

Returns: None
1
AnswersWidget.goToCategory(CATEGORY_ID)

AnswersWidget.goToChat()

Open the chat contact form in the widget screen.

Returns: None
1
AnswersWidget.goToChat()

AnswersWidget.goToContact()

Open the email contact form in the widget screen. Also see AnswersWidget.fillContactForm.

Returns: None
1
AnswersWidget.goToContact()

AnswersWidget.hasActiveChatConversation()

Get whether the user started a chat that was not finished and closed. A return of false indicates that no chat was started, or any chats have been closed.

Returns: Promise that resolves to a Boolean
1
2
3
4
5
6
7
var result = await AnswersWidget.hasActiveChatConversation();

// or

AnswersWidget.hasActiveChatConversation().then(function(result){
// do something with result
})

AnswersWidget.hide()

Hide the widget.

Returns: None
1
AnswersWidget.hide()

AnswersWidget.identifyUser({name: username:string, email: email-address:string})

Set the user's email address, for chat, email, or callbacks.

Returns: None
1
AnswersWidget.identifyUser({email: 'iknowyouremail@gmail.com'});

AnswersWidget.injectToElementById(DOM-ID:string)

Inject the widget view into a DOM element. The DOM element must be empty.

Returns: None
1
AnswersWidget.injectToElementById(DOM_ELEMENT_ID)

AnswersWidget.onChatMessageReceived(listener:function)

Execute a callback when a chat message is received.

Returns: None
1
AnswersWidget.onChatMessageReceived(callback);
The callback is called with the following parameters:
1
2
3
4
5
6
{
    messageId: <GUID>,
    ticketId: <GUID>,
    agentMessageIdx: <integer>, // The number message from the agent
    agentId: <GUID>
}

AnswersWidget.onChatMessageSent(listener:function)

Execute a callback when a chat message is sent.

Returns: None
1
AnswersWidget.onChatMessageSent(callback);
The callback is called with the following parameters:
1
2
3
4
5
6
{
    messageId: <GUID>,
    ticketId: <GUID>,
    userMessageIdx: <integer>, // The number message from the user
    isFile: <Boolean> // Whether the message is a file
}

AnswersWidget.onChatStarted(listener:function)

Execute a callback when a chat starts.

Returns: None
1
AnswersWidget.onChatStarted(callback);
The callback is called with the following parameters:
1
2
3
{
    ticketId: <GUID>
}

AnswersWidget.onDragEnd(listener:function)

Execute a callback function immediately after the user finishes dragging the widget.

Returns: None
1
AnswersWidget.onDragEnd(callback)
The callback is called with the following parameters:
1
2
3
4
{
    x: <integer>, // Target X offset from its initial location, in pixels
    y: <integer>  // Target Y offset from its initial location, in pixels
}

AnswersWidget.onLoaded(listener:function)

Execute a callback when the widget is loaded.

This is the only method available before the widget is loaded. Add all of your other code to the listener configured for this function.

Returns: None
1
2
3
window.AnswersWidget.onLoaded(function() {
    window.AnswersWidget.goToArticle('1324-13425-13542-1r4526');
} );

AnswersWidget.onTooltipClosed(listener:function)

Execute a callback when the tooltip is closed.

Returns: None
1
AnswersWidget.onTooltipClosed(callback);

AnswersWidget.onWidgetClosed(listener:function)

Execute a callback when the widget screen is closed.

Returns: None
1
AnswersWidget.onWidgetClosed(callback);

AnswersWidget.onWidgetOpened(listener:function)

Execute a callback when the widget screen is opened.

Returns: None
1
AnswersWidget.onWidgetOpened(callback);

AnswersWidget.open()

Open the widget screen.

Returns: None
1
AnswersWidget.open()

AnswersWidget.sendChatMessage({content: message:string})

Add a "bot message" to a chat.

Returns: None
1
AnswersWidget.sendChatMessage({content: 'Your message goes here'});

AnswersWidget.setCustomFields({field-name:string : value:*, ...})

Set custom fields for a chat, ticket, or callback. * The value types depend on the custom field.

Returns: None
1
AnswersWidget.setCustomFields({firstFieldName: 'first field value', secondFieldName: 'second field value'});

AnswersWidget.setLabels([label:GUID, ...])

Set the labels that are automatically added to all new tickets, chats, and callbacks.

Returns: None
1
AnswersWidget.setLabels(["bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa","e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a"])

AnswersWidget.setLauncherIconSvg(SVG:string)

Set the launcher icon to the passed SVG content string.

Returns: None
1
AnswersWidget.setLauncherIconSvg(svg)

AnswersWidget.setOffset(X-pos:integer,Y-pos:integer)

Set the location of the widget on the page, relative to the widget's initial X and Y position. X and Y can be positive or negative.

Returns: None
1
AnswersWidget.setOffset(300,500)

AnswersWidget.setOverrideTexts({text-field-name:string : value:string, ...})

Override texts in the widget.

You can find the text field names in the Help Center at Settings > New Widgets; select the Help row; select the Advanced tab; in Language Text Settings, select Edit (or navigate to https://<tenant_subdomain>.wixanswers.com/app/settings/widgets/{GUID}/advanced/{locale}/texts).

The input structure is a map of field names to values.

Returns: None
1
2
3
4
AnswersWidget.setOverrideTexts({
    "widget-v3.widget-launcher.icon-message": "Hi!", 
    "widget-v3.widget-home.contact-button.contact-title": "Contact Us!"
})

AnswersWidget.setTooltipConfig(tooltip-text:string, delay-in-seconds:integer)

Set the contents and delay of the widget tooltip that appears when the page with the widget is first loaded. The default delay is 0.

Returns: None
1
AnswersWidget.setTooltipConfig(tt_content,2)

AnswersWidget.setUnreadMessageConfig(background-color:string,show-on-no-unread:Boolean)

A badge with the unread message count may appear when the user closes the widget when there is an active chat in progress. Use this to configure the tooltip background, and whether to show the tooltip even when there are no unread messages (the default is false}.

Returns: None
1
AnswersWidget.setUnreadMessageConfig("#ffffff",true)
The default background color is #389eec.

For example, the closed widget appears as follows if there are no unread messages, and the second argument is set to true.
The closed widget appears as follows if there are two unread messages.

AnswersWidget.show()

Display the widget.

Returns: None
1
AnswersWidget.show()
IN THIS ARTICLE

Related Articles

Creating a New Widget

Allow customers to get help without navigating away from your product or website with the Wix Answers Widget. Create a widget to present knowledge base articles and allow customers to get support via contact form, Live Chat, or phone support. Create as many widgets as you need and tailor them to the locations where you are adding them. Note:We're currently in the process of releasing a new version of the Wix Answers Widget. If you don't see the steps below in your widget settings, click here for directions. To create a new widget:Hover over Settings  and click Widgets.Click Create New Widget.Enter a name for your Widget and click Create Widget.Next:Customize your WidgetAdd contact options to your WidgetAdd a contact widget to your Help CenterAdd your Widget to your non-Wix websiteAdd your Widget to your Wix site

1 min read

Customizing Your Widget

Tailor your Widget to your business' needs by customizing its components, appearance, and more. While customizing your Widget, preview its look and behavior at the right side of your screen. Note:We're currently in the process of releasing a new version of the Wix Answers Widget. If you don't see the steps below in your widget settings, click here for directions. Customizing Your Widget's Structure &amp; ContentCustomize your Widget's content and components from the Structure &amp; Content tab. Show me howHover over Settings  and click Widgets.  Hover over the Widget you'd like to customize and click Edit.(For multilingual widgets): Click the language next to Settings for and select a language. Customize your Widget's Header Text:Enter a title for your Widget.(Optional): Click Display Subtitle and enter a subtitle for your Widget.Click Confirm. Customize your Widget's Launcher Text:Click Add a Welcome Message and enter your message. Click Delay the Welcome Message and enter the amount of seconds you'd like to delay your message. Click Confirm.Choose the components and the order in which they appear in your Widget:Add: Click Add Component and select a component to add it to your Widget. Manage: Click Manage next to a component to edit it. Remove: Click the Vertical Show More icon  and select Remove component. Hide contact option: Click the Toggle to enable or disable a contact option. Reorder component: Click and drag the Reorder icon  to reorder a component. Learn more about:Setting up your Widget's contact optionsChoosing which articles customers can access in your WidgetAdding a Custom HTML Box to your WidgetCustomizing Your Widget's Design &amp; BrandingCustomize your Widget's appearance, icon, and position from the Design &amp; Branding tab. Show me howHover over Settings  and click Widgets.  Hover over the Widget you'd like to set up and click Edit.Click the Design &amp; Branding tab. Edit the Widget Appearance settings:Choose your Widget colors: Click Edit in the Header &amp; Launcher Color section and enter a HEX number. Click Edit in the Action Color section and enter a HEX number. Select a background pattern next to Background. Click the Font drop-down menu and select a font. Click the Hide the Wix Answers Banner checkbox to hide the &quot;Powered by Wix Answers&quot; message that appears at the bottom of the widget. Edit your Icon Appearance settings:Select the icon customers click to open your Widget next to Image. Customize the Shape &amp; Size of the Widget icon:Click Large or Small to select an icon size. Click and drag the Shape slider to make your icon's corners more or less round. (Optional) Click the Make Your Icon &amp; Widget Draggable checkbox to allow customers to click and drag your Widget to anywhere on their screen. Edit the Widget Position settings:Select a Position icon to choose which side of the screen your Widget appears. Click the Side Spacing arrows to adjust the distance between your Widget and the side of the screen.Click the Bottom Spacing arrows to adjust the distance between your Widget and the bottom of the screen.Click Update at the top of the page.Customizing Your Widget's Advanced SettingsOn the Advanced tab, you can customize the widget text for each language, add custom CSS and scripts, whitelist domains, and restrict access to authenticated users. Show me howHover over Settings  and click Widgets.  Hover over the Widget you'd like to set up and click Edit.Click the Advanced tab. Edit your Widget's Advanced settings:Translate the text for each of your supported languages:Click Edit next to the relevant language.    Scroll to the text you'd like to translate or enter it in the Search field. Click the text under Line and translate it.Note: Hover over the text and click Revert on the right to revert it. Click Save.Add custom code:Custom CSS: Click + Add CSS, enter your CSS code and click Save.Custom Script: Click + Add Script, enter your JavaScript code and click Save.Whitelist domains:Click Edit in the Domain Whitelisting section.    Enter the domain(s) you'd like to allow your Widget to be displayed on.Note: Press Enter on your keyboard to add multiple domains. Click Save.Click the Restricted Access toggle  to make your Widget only accessible to authenticated users. Learn how to:Add a contact widget to your Help CenterEmbed a contact widget on your non-Wix websiteEmbed a contact widget on your Wix site

4 min read