Creating custom controls for the IVA for Web Chatbot

Improve how users interact with Pega Intelligent Virtual Assistant (IVA) for Web Chatbot by implementing your own user input controls for the chatbot. By implementing custom controls you ensure a better overall user experience, and that the IVA meets the needs and requirements of your organization. For example, when a chatbot displays your custom controls, such as an autocomplete field, users can obtain help and resolve their issues more quickly.

To create your own custom control for the IVA for Web Chatbot, you must define a class that inherits from Embed-Channel-Control- in the following format: Embed-Channel-Control-<custom_control_name>. For example, to create a custom control that is used as an autocomplete field, you create the Embed-Channel-Control-Autocomplete class in the system. For more information, see Working with custom controls in the IVA for Web Chatbot.
  1. Create a new abstract class for your custom control in the following format: Embed-Channel-Control-<custom_control_name>.
    For example: To define a custom control that is used as an autocomplete field, save the following class: Embed-Channel-Control-Autocomplete
  2. Open the Embed-Channel-Control-.pyDefault rule, save this data transform rule as Embed-Channel-Control-<custom_control_name>.pyDefault, and set pxIsSimpleMode to false.
    For example: For an autocomplete custom control, save the data transform rule as: Embed-Channel-Control-Autocomplete.pyDefault
  3. Override the Work-Channel-Interaction.pySetInputControl rule and trigger the pxCreateControlOfClass activity with Embed-Channel-Control-<custom_control_name> as its parameter.
    Note: Ensure that the chatbot does not always use this custom control by configuring the Embed-Channel-Control-<custom_control_name> rule to run only under certain conditions.
  4. Optional: To use a different type of input in the chatbot for the custom control, perform the following steps:
    1. Open the Embed-Channel-Control-.pyInput section rule.
    2. Save this rule as the Embed-Channel-Control-<custom_control_name>.pyInput section.
    3. Edit the section rule to customize the input, and then save your changes.
    Note: By default, the .pyText property is the value that the system sends to the chatbot. If you have not yet customized the Send button action, the control is based on this value. However, if you customize this section, you must ensure that the chatbot correctly handles events for the Send button. For more information, see Adding a text input control.
  5. Optional: To customize the style and behavior of the Send button in the custom control, perform the following steps:
    1. Open the Embed-Channel-Control-.pySubmitButton rule.
    2. Save this rule as the Embed-Channel-Control-<custom_control_name>.pySubmitButton section.
    3. Edit the section rule to customize the Send button and save your changes.
    Note: If you want the chatbot to process the message, you must trigger the pxProcessSimulation activity. To trigger this activity, ensure that you check the default action that is configured on the default button implementation.
  6. Optional: To add more action buttons in the custom control, perform the following steps:
    1. Open the Embed-Channel-Control-.pyActionButtons rule.
    2. Save this rule as the Embed-Channel-Control-<user_control_name>.pyActionButtons section.
    3. Edit the section rule to add more action buttons and save your changes.
    Note: By default, the IVA includes the Add attachment icon. You can add more action buttons in the section that the system displays below the input area of the chat window.
  7. Optional: To switch between the simple and advanced mode shown in the default text area of the custom control, perform the following steps:
    1. Open the Embed-Channel-Control-.pyOnSwitchToSimpleMode activity.
    2. Save this rule as the Embed-Channel-Control-<custom_control_name>.pyOnSwitchToSimpleMode activity.
    3. Edit the activity rule to switch to simple mode and save your changes.
      These steps ensure that you provide a value conversion when the pxSwitchToSimpleMode API is called, no matter whether the system uses a standard control or your custom control.
    4. Open the Embed-Channel-Control-.pyOnSwitchToAdvancedMode activity.
    5. Save this rule as the Embed-Channel-Control-<custom_control_name>.pyOnSwitchToAdvancedMode activity.
    6. Edit the activity rule to switch to advanced mode and save your changes.
      These steps ensure that you provide a value conversion when the pxSwitchToSimpleMode API is called, no matter whether the system uses a standard control or your custom control.
    Note: You can implement buttons to switch between the simple and advance modes in your chatbot by using the pxSwitchToSimpleMode API activity to switch the view to the default text area. You can also use the pxSwitchToAdvancedMode API activity to switch the view to Embed-Channel-Control-<custom_control_name>.pyInput. For more information about advanced configuration for controls such as the date control, see Advanced controls.
  8. Optional: To provide additional conversion of text entered in the custom control before the system submits this user input to the chatbot for processing, perform the following steps:
    1. Open the Embed-Channel-Control-.pyOnSubmit activity.
    2. Save this activity rule as Embed-Channel-Control-<custom_control_name>.pyOnSubmit.
    3. Edit the activity rule to provide additional conversion for the entered text, and then save your changes.
    Note: Performing additional conversion of user input is useful when there is no need to update the Send button, as the system calls this extension by default for all of the standard built-in controls used by the chatbot.
  9. Optional: To enable the addition of attachments for the custom control, perform the following steps:
    1. Open the Embed-Channel-Control-.pyAttachmentAddingEnabled when rule.
    2. Save this rule as Embed-Channel-Control-<custom_control_name>.pyAttachmentAddingEnabled.
    3. Modify the when rule so that it returns true, and then save your changes.
  10. Optional: To customize a section that the system displays above the input area in the chat window, perform the following steps:
    1. Open the Embed-Channel-Control-.pyActionsBar section rule.
    2. Save this rule as the Embed-Channel-Control-<custom_control_name>.pyActionsBar section.
    3. Edit the section rule used for the input area, and then save your changes.
    4. To make the custom section visible when your custom control is used, open the Embed-Channel-Control-.pyShowActionsBar when rule.
    5. Save this rule as Embed-Channel-Control-<custom_control_name>.pyShowActionsBar.
    6. Modify the when rule so that it returns true, and then save your changes.
    Note: The chatbot displays a custom section above the input area that contains standard controls, such as quick replies.