Using the Widget for Contextual Help: Pages to Recommend On

As of August 2022, we have deprecated the Legacy and Modern widgets. See Deprecation of Modern & Legacy widget for more information.

Pages to Recommend On allows you to provide contextual help to your readers through the embeddable contact form widget or the API. You can provide a list of relevant articles based on the page the person opened the widget from, which may eliminate the need for them to search the knowledge base or contact you.

You can relate individual articles to pages in your knowledge base, website, or application so that they are suggested when the widget loads on the page, or you use the API to return articles for a particular page in your site. For example, if you associate articles with the "/pricing" page on your website, these articles appear when the embeddable contact form loads on this page. Alternatively, if you associate articles with the "/account" page in your application and use the API to pull articles for that page, these articles will be returned for your "/account" page.

The exact display is different depending on which widget type you've selected.

If you're using the Modern Slideout widget, this impacts the Suggested Articles header section (in Settings > Widget, you can designate a different name for this section, so it may be called something else):

Screenshot showing the Modern Widget, with callout to the Suggested For You sectionSample Modern widget, Suggested For You section

In order to start using this feature, you'll need to:

  • Set the Widget Settings to use the appropriate Suggested Content setting
  • Add URLs from your main application or website to the articles or categories you'd like to recommend in the widget or API

Configuration - Widget settings

First, check your widget's settings and be sure that the Suggested Content option best matches how your website or application is set up:

  1. Go to Settings > Widget.
  2. In the Admin Settings section, look for Suggested Content. This has three options:
    • Suggest content based off of the page path (default): use this setting if the website where you're embedding the widget uses the URL or page path to differentiate pages. For example, we use this setting for the widget in this support knowledge base, since our page URLs are formatted without query strings and with no special characters.
    • Use the page query strings to suggest content: use this setting if you want to recommend based on query strings, which appear in the URL as ?variable=, such as ?s= or ?client= for example. If your website's URLs don't have query strings--or the query strings aren't meaningful for recommendation distinctions--don't use this setting.
    • Disable automatic page suggestions: this setting is not available in Modern Slideout and Legacy widgets
      The Suggested Content options in the Admin Settings section
  3. Select the option that best fits the URLs of the website where you're embedding the widget.
  4. Be sure to Save your setting change.

Configuration - Articles & categories

Now you can add URLs from your website to the articles or categories you'd like to recommend in the widget or API.

These should be relative URLs. If we are configuring articles for https://www.knowledgeowl.com, we will only take the portion of the URL that comes after that URL. For example, https://www.knowledgeowl.com/pricing becomes "/pricing". Specifically, the pathname of the URL is sent. The fragment and query string are not sent (unless you've selected the option to use query strings! Then you'd want to use query strings here.)

Once you have the relative URL for pages you want to specify recommended articles for, open one of those articles in the article editor in KnowledgeOwl.

Add the relative URL to the Recommend On Pages section, then select Save.

If you want this article to be recommended on multiple pages in your application or website, add each relative URL on a separate line:

If your website or application includes URLs that have a variable ID field in them, you can replace that ID with {id} in your URL:

Note: {id} only works with numeric and 24-digit hexadecimal IDs. For IDs that don't match either of those patterns, you would need to use the {custom} option via regex.

Be sure to save the article. The next time someone opens the widget from one of those pages in your site or application, it will suggest this article.

The default behavior to send the URL of the page for recommendations can be overridden. This is important in cases where the page doesn't change like in a single page application or if the URLs themselves do not fit well within this framework. We have a guide for implementing this in single page applications. 

Ordering recommended articles

If you've added several recommended articles and you'd like to set the order they display in, you can change the order in by editing the article weights for that page in Widget > Reporting. See Recommended Article Weights for more information.