Widget Client SDK - Chatbot Feature

The chatbot feature of the Widget Client SDK provides chatbot flows for your Wix Answers widget. A chatbot is an automated chat script for users to interact with. The chatbot can help some users obtain information or answers without requiring attention from a live agent. Users can seamlessly transition from interacting with the chatbot to a Help Center article, a contact form, or live chat with an agent, as required.

You can configure the steps and flows of the chatbot. The feature supports simple flows with basic logic implemented client-side. It is part of the general Widget Client SDK, so you can provide more complex flows by integrating the chatbot with other SDK methods, external APIs, or other external platforms.
Example uses of the chatbot include:
  • Set labels or custom fields for the chat ticket based on user input.
  • Open an article or category based on user input.
  • Present a callback/contact form outside of working hours.

The Chatbot Flow

The chatbot is built around configurable steps (objects). To initiate the chatbot flow, call the method initiateChatbot with the first step in the flow, the handling function for the user response, and the chatbot name. There are four types of steps:
  • Text: Prompt for user text input
  • Button: Prompt for user to select a button
  • Contact: Present contact options that open the relevant contact form
  • Live chat: Exit the chatbot and initiate a live chat with an agent
As the user interacts with the chatbot (for example, selects a button or enters text), the widget invokes the handling function, passing the user's response, and receives the next handling function in response.

Methods

AnswersWidget.initiateChatbot(firstFn:function, handlerFn:function, HTML:string)

Initiate the chatbot.

Parameters:
  • <firstFn> (Structure): The first step in the flow. The feature presents the first step in the chatbot, and typically displays a prompt for some kind of user response.
  • <handlerFn> (Function): The function to run after the user enters text or selects a button. This function parses the user input and sends the next step to display new messages and a new prompt to the user.
  • <HTML> (String, optional): The name of the chatbot to appear in the chat header. The default name is "Chatbot".


For example:
1
2
3
4
window.AnswersWidget.onLoaded(() => {
  window.AnswersWidget.goToChat();
  window.AnswersWidget.initiateChatbot(firstStep, chatBotCallback, 'Very good Chatbot')
});
Examples of firstStep and chatBotCallback are presented below.

See a working CodePen example.

Step Types and Parameters

There are four types of chatbot steps: text, button, contact, and live chat. Each step is an object with specific parameters.

Text Step Parameters

Prompt for user text input.
  • id (String): A unique ID
  • type (String): Must be text
  • messages (Array of structures): Chat messages to present before prompting the user to enter text, in order, as follows:
    • content (String): The chat message, up to 65,519 bytes
    • typingDelay (Integer): Delay before presenting the message, in ms
  • shouldBlockInput (Boolean, optional): Unless you want to end the chat conversation, this must be false. The default is false.

Example:
1
2
3
4
5
6
7
const searchArticlesStep = {
  id: '5',
  type: 'text',
  messages: [
    {content: 'Search something:', typingDelay: 1000}
  ]
};

Button Step Parameters

Prompt for user to select a button. If you display a text box, then the chatbot handles the request either after the user selects a button or after the user enters text and presses Enter. Typically, you want to hide the text box in a button step.
  • id (String): A unique ID
  • type (String): Must be button
  • messages (Array of structures, optional): Chat messages to present before prompting the user to select a button, in order, as follows:
    • content (String): The chat message, up to 65,519 bytes
    • typingDelay (Integer): Delay before presenting the message, in ms
  • buttons (Array of structures): Buttons to present to the user, in order, as follows:
    • content (String): Button text. We recommend using a string up to 64 characters.
    • value (String): Value to submit when user selects this button
    • leaveOnSelect (Boolean, optional): When true, the buttons disappear after the user selects one. The default is false.
  • shouldBlockInput (Boolean, optional): When true, the user is not presented with the option to enter text instead of selecting a button. The default is false.

Example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
const firstStep = {
  id: '1',
  type: 'button',
  shouldBlockInput: true,
  messages: [
    {content: 'Hi!', typingDelay: 1000},
    {content: 'What do you want to do?', typingDelay: 1000}
  ],
  buttons: [
    {content: 'Check my balance', value: 'balance'},
    {content: 'Talk to an agent', value: 'agent'},
    {content: 'Contact you', value: 'contact'},
    {content: 'Search for an article', value: 'search'},
  ]
};

Contact Step Parameters

Present contact options (Email, New Chat, Phone Callback) that open the relevant contact form (see goToContact(), goToChat(), or goToCallback(), respectively). You can hide options that are disabled for your site.

If you display a text box, then the chatbot handles the request either after the user selects a contact option or after the user enters text and presses Enter. Typically, you want to hide the text box in a contact step.
  • id (String): A unique ID
  • type (String): Must be contact
  • messages (Array of structures, optional): Chat messages to present before prompting the user to select a contact option, in order, as follows:
    • content (String): The chat message, up to 65,519 bytes
    • typingDelay (Integer): Delay before presenting the message, in ms
  • hideDisabledOptions (Boolean, optional): When true, hide any disabled contact options. The default is false.
  • shouldBlockInput (Boolean, optional): When true, the user is not presented with the option to enter text instead of selecting a contact option. The default is false.

Example:
1
2
3
4
const contactStep = {
  id: '4',
  type: 'contact'
};

Live Chat Step Parameters

Exit the chatbot and initiate a live chat with an agent.
  • id (String): A unique ID
  • type (String): Must be live-chat
  • messages (Array of structures, optional): Chat messages to present before exiting the chatbot, in order, as follows:
    • content (String): The chat message, up to 65,519 bytes
    • typingDelay (Integer): Delay before presenting the message, in ms
  • startImmediately (Boolean, optional): When false, open live chat and wait for user input before creating the ticket and assigning to an agent. When true, open live chat and immediately create a ticket and assign to an agent. The default is false.

Example:
1
2
3
4
const liveChatStep = {
  id: '3',
  type: 'live-chat'
};

The Handling Function (Callback)

The callback function should process the user's response and return the next step in flow. The callback is invoked after each text, button, or contact step with the following parameters:
  • input (String): The user input from a text step or the selected value from a button step.
  • type (String): The type of the step: text, button, or contact. Note that a live chat step ends the chatbot, and so does not invoke a callback.
  • stepId (String): The ID of the step.

Example Implementation

The steps:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
const firstStep = {
  id: '1',
  type: 'button',
  shouldBlockInput: true,
  messages: [
    {content: 'Hi!', typingDelay: 1000},
    {content: 'What do you want to do?', typingDelay: 1000}
  ],
  buttons: [
    {content: 'Check my balance', value: 'balance'},
    {content: 'Talk to an agent', value: 'agent'},
    {content: 'Contact you', value: 'contact'},
    {content: 'Search for an article', value: 'search'},
  ]
};

const getBalance = async () => {
  return 100;
}

const getArticles = async (text) => {
  return [1, 2, 3].map((n) => text + ' ' + n);
}

const getCheckBalanceStep = async () => {
  const balance = await getBalance();
  return {
    id: '2',
    type: 'button',
    shouldBlockInput: false,
    messages: [
      {content: 'Your balance is' + balance + '$', typingDelay: 1000}
    ],
    buttons: [
      {content: 'Go back to first step', value: 'first-step'},
    ]
  };
};

const liveChatStep = {
  id: '3',
  type: 'live-chat'
};

const contactStep = {
  id: '4',
  type: 'contact'
};

const searchArticlesStep = {
  id: '5',
  type: 'text',
  messages: [
    {content: 'Search something:', typingDelay: 1000}
  ]
};

const getArticlesStep = async (text) => {
  const articles = await getArticles(text);
  return {
    id: '6',
    type: 'button',
    shouldBlockInput: true,
    messages: [
      {content: 'Results:', typingDelay: 1000}
    ],
    buttons: articles.map(articleName => ({
      content: articleName, value: articleName,
    }))
  };
};
The callback:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
const chatBotCallback = (input, type, stepId) => {
  if (input === 'balance') {
    return getCheckBalanceStep();
  } else if (input === 'agent') {
    return liveChatStep;
  } else if (input === 'contact') {
    return contactStep;
  } else if (input === 'search') {
    return searchArticlesStep;
  } else if (type === 'text') {
    return getArticlesStep(input);
  } else {
    return firstStep;
  }
}
The initial method call:
1
2
3
4
window.AnswersWidget.onLoaded(() => {
  window.AnswersWidget.goToChat();
  window.AnswersWidget.initiateChatbot(firstStep, chatBotCallback, 'Very good Chatbot')
});
IN THIS ARTICLE