Using chat with documents

You can enable the chat with documents feature in your conversational search configuration, which allows users to query their conversational search bot, while restricting it to only search specified documents for an answer.

There are multiple ways in which a user can select a document to chat with:

  • From the search results page: Clicking the Sources button under the response displays a list of documents that powered the bot's response. Selecting one of these documents displays a drop-down list of possible actions. From this list, users can click Chat with document to filter and restrict their next conversational search query to only use the selected documents.

  • From the related documents panel: Clicking beside a related document in the side panel displays a drop-down list of possible actions. From this list, users can click Chat with document to filter and restrict their next conversational search query to only use the selected documents.

  • From the SmartHub Basket: After adding documents to the SmartHub basket, users can select their basket and choose whether to chat with all or specific selected documents in their basket.

Prerequisites

Note the following prerequisites when using chat with documents

  • Chat with documents can only be used with conversational search in SinglePage and Hybrid integrations.

  • To use Chat with Documents functionality, you must enable the ChatWithDocuments setting in the Content Container module used for SmartHub search main results and the related documents.

  • If you wish to use Chat with documents from the SmartHub basket, you must set up a SmartHub basket on your page and enable the EnabledInBasket setting.

  • If you wish to use the SmartHub Basket in your Conversational Search page for source documents, you must set up a SmartHub basket on your page and enable the EnabledInConversationalSearch setting.

Add chat with documents functionality

To add chat with documents functionality to your conversational search page, you can enable the feature through the UI Editor.

  1. In the SmartHub administration portal, click UI Editor.

  2. Click Select a page from the top menu.

  3. Select an HTML page, such as the Results.html page.

    1. Upland BA Insight recommends that you use a custom page and folder when modifying your settings. Leave the default files as templates.

    2. For example, Customizations/CustomResults.html. Copy the code from the default Results.html page, located at the top most SmartHub directory. For more information, see Creating custom pages.

  4. Select the Advanced mode from the top right of the page.

  5. Select Advanced Settings Edit.

  6. Scroll down and locate the text SH.ChatWithDocuments.CustomSettings

    SH.ChatWithDocuments = SH.ChatWithDocuments || {};
    SH.CHatWithDocuments.CustomSettings = {};

  7. Click Default Settings at the top right.

  8. A new browser tab opens with all the available SmartHub module settings.

  9. Search for the word "ChatWithDocuments" on the page to quickly navigate to the default settings, shown below:

    SH.ChatWithDocuments = SH.ChatWithDocuments || {};
    SH.ChatWithDocuments.DefaultSettings = {
        Enabled: "true",
        EnabledInBasket: "true",
        ChatBotMode: "SinglePage",//SinglePage, //Hybrid
        BasketKey: ".basketButton",
        BasketSelectionBtnClass: "chat-doc-selector"
        BasketLabelChatWithAllDocuments: "Chat with all favorite documents",
        BasketLabelChatWithSelectedDocuments: "Chat with selected documents",
        ConversationalSearchBotID: "ConversationalSearchBot",
        WarningMessage: "This document is already active in the chat session",
        WarningMessageSelector: ".sh-row-body.sh-body-grid.covero-main-selection .sh-column-right",
        ConversationalSearchPagePath: "/ConversationalSearch.html",
        DocumentTitleProperty: "title",
        DocumentExtensionProperty: "FileExtension",
        PropertyUsedForRestriction: "clickUri",
        InfoMessageTemplatePath: SH.RootLevelURL + "/modules/ChatWithDocument/templates/InfoMessageTemplate.html",
        ModuleDetails:{
            label: 'Chat with document',
            btnClass: 'chat-with-document'
        }
        
    }

  10. Copy the ChatWithDocuments settings section from SH.ChatWithDocuments.DefaultSettings.

  11. Go back to your Advanced settings edit tab.

  12. Paste the copied settings into the SH.ChatWithDocuments.CustomSettings section.

  13. Modify settings as desired. Refer to the Chat With Document settings parameters table below.

  14. Click Save changes.

  15. Click the Preview <html> file.html link at the top of the code editor.

  16. Review your HTML page in the new tab that opens.

  17. Make any necessary changes back in the code editor. Repeat steps 14-18 as necessary.

  18. Click Save changes.

Chat With Document settings parameters

Setting Description Default value
Enabled

This setting enables or disables the chat with document feature for conversational search. The possible values for this setting are:

  • true

  • false

 true
EnabledInBasket This setting enables or disables the basket for the chat with document feature, allowing users to add selected documents to their basket, which they can then use to filter their conversational search chat when needed. The possible values for this setting are:

  • true

  • false

 true
ChatBotMode

This setting specifies the conversational search mode that is applied. The possible values for this setting are:

  • SinglePage

  • Hybrid

 "SinglePage"
BasketKey This setting specifies the name of the SmartHub basket, as configured in the SmartHub Basket instructions. ".basketButton"
BasketSelectionBtnClass This setting specifies the class name of basket button on the results page. "chat-doc-selector"
BasketLabelChatWithAllDocuments This setting specifies the text that is displays for the "Chat with all documents" control in the SmartHub basket. "Chat with all favorite documents"
BasketLabelChatWithSelectedDocuments This setting specifies the text that is displays for the "Chat with selected documents" control in the SmartHub basket. "Chat with selected documents"
ConversationalSearchBotID This setting specifies the ID for your conversational bot, as configured in the conversational search instructions. "ConversationalSearchBot"
WarningMessage This setting specifies the text that is displays when a user attempts to add the same document to a chat session. "This document is already active in the chat session"
WarningMessageSelector This setting specifies where the warning message will render on the page. ".sh-row-body.sh-body-grid.coveo-main-section .sh-column-right"
ConversationalSearchPagePath This setting specifies the path to your conversational search page. "/ConversationalSearch.html"
DocumentTitleProperty This setting specifies the field to use to populate the title of the document. "title"
DocumentExtensionProperty This setting specifies the field to use to populate the file extension of the document. "FileExtension"
PropertyUsedForRestriction   "clickUri"
InfoMessageTemplatePath This setting specifies the path to the info message template file. SH.RootLevelURL + "/modules/ChatWithDocument/templates/InfoMessageTemplate.html"
ModuleDetails This setting specifies the UI labels and text that the user can customize without creating a new html template. For more information, see ModuleDetails Parameters. -