URL Mapping

Updated
  • Updated on Oct 25, 2025
  • Published on Jun 5, 2024
  • 9 minute(s) read
Prev Next

Plans supporting this feature: Business Enterprise

The URL Mapping feature within the knowledge base widget allows you to tailor the display of specific articles and categories based on the pages your end users visit. This functionality not only enhances user experience by directing users to relevant content but also enables you to hide the knowledge base widget on certain URLs or provide a search bar with custom placeholders, guiding users on what to search.

Using URL mapping

To configure URL mapping, you perform specific actions within the knowledge base widget for designated URLs.

Actions

There are four actions you can execute with URL mapping:

  1. Show article: Displays a single article on the specified URL.

  2. Show list of articles: Lists selected articles under the Recommended section within the Knowledge Base widget on the specified URL.

  3. Show search results: Allows you to set a specific search term to query your knowledge base, returning relevant search results on the specified URL.

  4. Hide widget: Prevents the Knowledge Base widget icon from appearing on the specified URL.

You can find these actions under the URL Mapping tab or when editing an existing mapping.

NOTE

For URL Mapping to work, the Knowledge base widget must be installed within your site or app. For more information, read the article on Installing the Knowledge base widget.

URL Parameters

When configuring the Knowledge Base widget URL, you can include three types of parameters:

  1. Include Path: /thisis/a/path

  2. Include Query: ?animal=bear

  3. Include Hash: #inbox

You can also enable the Is Regex toggle to incorporate regular expressions into your URL configurations.

Adding URL mapping to your Widget

To integrate the desired widget into your knowledge base site, follow these steps:

  1. Navigate to Knowledge base Widget () in the left navigation bar of your Knowledge base portal.

  2. Click the URL Mapping tab.

  3. Click New URL mapping and specify the following:

    • Name - The URL Mapping name will only be shown on the URL mapping record within Document360

    • URL structure  - Select the desired URL parameter type (Include path/Include query/Include hash). You must enable at least one URL parameter

    • Type in the URL on which you want the article/category to show or the action to occur.

      NOTE

      Your domain name is not included in the URL path. For instance, https://document360.com/ebook/rapid-guide-to-launch-your-knowledge-base/, your URL Path would be /ebook/rapid-guide-to-launch-your-knowledge-base/

    • Action - Select the desired action.

    • Select workspace - Select the desired version (if you have multiple versions).

    • Language to - Select the desired language (if you have multiple languages).

    • Article to show - In the search bar, select the articles/categories you want to show from your knowledge base documentation.

    NOTE

    Folder categories are not available for selection. Only page and index category types are available for selection.

  4. Click Create.

Once an end user accesses your specified URL path and opens the Knowledge Base widget, they will see the mapped article/category. This information remains consistent as they navigate between the Knowledge Base widget tabs within the same version and language.

Configuring Contextual AI assistance

The Contextual AI assistance option lets you display AI-powered prompts in the Knowledge base widget. Based on your configuration, these prompts can appear either when users click a button or automatically when they open a specific page along with the answer to the prompts.

URL mapping settings with contextual AI assistance feature highlighted for user configuration.

NOTE

To configure Contextual AI assistance, ensure that AI assistive search is enabled for the widget.

Understanding prompting types

You can configure Contextual AI assistance in two ways.

  1. Button-based prompting

  2. Page-level prompting

Button-based prompting

Use this option to display context-aware help when readers click specific buttons on your website or app.

  • Each prompt you add generates a unique Trigger key.

  • The prompt is automatically validated on hitting Enter to confirm whether an answer is found in your connected sources.

  • You can either update an existing button by adding the custom attribute d360AIHelp with the Trigger key as its value, or create a new button by copying the Installation code snippet and pasting it into your HTML.

  • When the button is clicked, the widget opens automatically and displays the configured AI prompt with its corresponding answer.

  • You can configure up to 5 button–prompt mappings per URL.

  • If multiple buttons are configured on the same page:

    • The prompt for the clicked button is displayed first.

    • Prompts from other buttons appear in the widget as related or suggested queries.

Page-level prompting

Use this option to provide AI-driven help automatically when users open a specific page, without requiring any button interaction.

  • To choose this option, select Enable page-level prompting during Contextual AI assistance configuration.

  • Add one or more prompts that will trigger when users access the configured URL. The prompt is automatically validated on hitting Enter to confirm whether an answer is found in your connected sources.

  • You can add up to 5 prompts per page.

    • The first prompt is shown as the primary question.

    • Remaining prompts appear as suggested queries.

Adding, validating, and removing prompts

For button-based prompting

  1. In the Configure contextual AI assistance section, leave the Enable page level prompting unchecked.

Configuration options for enabling contextual AI assistance in Document360 widget settings.

  1. Next, enter your Search prompt.

  2. Press Enter to validate the prompt.

    • If the system finds an answer, it displays Answer found beside the prompt as a green label.

    • If no matching result is found, the system displays Answer not found as a red label.

  3. If you are updating an existing button, copy the Trigger key and add it to the existing button’s code using the d360AIHelp attribute.

    For example,

    <button d360AIHelp="no6gNpyDqtyBhCVFMhYDXhugZ">Need help?</button>

Instructions for adding URL mapping and search prompt in Document360 widget settings.

  1. If you are creating a new button, click Copy code next to Installation code to create the new button, then paste the snippet into your page’s HTML.

Instructions for adding URL mapping and contextual AI assistance in Document360 widget.

  1. To add another button-based prompt, click Add more and repeat the process.

  2. To remove a prompt, click Remove next to the respective entry.

For page-level prompting

Configuration options for Document360 widget, highlighting page level prompting feature.

  1. Select the Enable page-level prompting checkbox.

  2. In the Search prompt field, enter your query.

  3. Press Enter to validate the prompt.

    • If the system finds an answer, it displays Answer found beside the prompt as a green label.

    • If no matching result is found, the system displays Answer not found as a red label.

  4. To add another prompt, click Add more and enter a new query. Repeat until you’ve added up to four prompts for that URL.

  5. To delete a prompt, click Remove beside the prompt field.

Once you have configured either button-based or page-level prompts, click Create.

You can mix standard URL mapping actions (such as Show article) with Contextual AI assistance across different URLs to deliver a tailored, intelligent user experience.

Editing URL mapping

To modify an existing URL mapping:

  1. Navigate to Knowledge base Widget () in the left navigation bar of your Knowledge base portal.

  2. Hover on the desired Knowledge base widget and click the Edit () icon.

    In the URL mapping tab, you can find the list of available URL mapping.

  3. Hover over the desired URL mapping and click the Edit () icon.

    The Update URL mapping panel will appear.

  4. Update the desired information and click Update.

2_urlmapping_edit.gif

Deleting URL mapping

You can delete a set URL mapping.

3_urlmapping_delete.png

  1. Navigate to Knowledge base Widget () in the left navigation bar of your Knowledge base portal.

  2. Hover on the desired Knowledge base widget and click the Edit () icon.

  3. In the URL mapping tab, you can find the list of available URL mapping.

  4. Hover over the desired URL mapping and click the Delete () icon.

  5. Click Yes in the Delete confirmation prompt.

URL mapping settings

You can define the Knowledge base widget behavior for URLs that do not have a configured mapping. Defining this behavior can improve the user experience and accessibility to the documentation.

4_urlmapping_settings.png

  1. Navigate to Knowledge base Widget () in the left navigation bar of your Knowledge base portal.

  2. Click the Configure & connect tab.

  3. Under the Set controls section, expand the URL mapping settings section.

  4. Select the desired option:

    • Navigate to the page help/knowledge base: Select this option to display the article/category in the Page help or Knowledge base tab in the Widget.

    • Do not make any changes to the existing setup: Select this option to display the last opened article/category in the Widget.

  5. Click Save.

Basic URL matching

Understanding URL matching is crucial for effective URL mapping. A general-purpose regex for matching typical URLs looks like this:

^https?://?[a-zA-Z0-9.-]+/[a-zA-Z0-9/._-]*??[a-zA-Z0-9=&._-]*?#[a-zA-Z0-9_-]*?$

Explanation of the components

  • ^https?://?: Matches the protocol (e.g., http:// or https://). The ? makes the protocol optional.

    NOTE

    Ensure to add a backward slash (\) before every forward slash (/) while testing your URL on https://regex101.com.

  • [a-zA-Z0-9.-]+: Matches the domain name, including letters, numbers, dots (.), and hyphens (-).

  • /[a-zA-Z0-9/._-]*?: Matches the path after the domain, allowing slashes, alphanumeric characters, dots, underscores, and hyphens.

  • ?[a-zA-Z0-9=&._-]*?: Matches optional query parameters (e.g., ?key=value), making this part optional.

  • #[a-zA-Z0-9_-]*?: Matches the fragment (e.g., #section), which is also optional.

Examples of URL mapping using Regex

Mapping specific URL structures

The following table shows how to configure URL mappings for certain URL patterns. These configurations help ensure accurate matching based on the URL path or query structure.

URL Structure

URL mapping configuration

/buckets

/buckets$
(Configure if the URL ends with buckets)

/buckets?isCreatingBucket

/buckets\?[a-z]*
(Configure if the URL has random texts after the query parameter)

Example matches

  • /buckets

  • /buckets?isCreatingBucket

  • /buckets?isCreatingBucket=true

To map a URL pattern like /users/{id}, use:

^/users/[0-9]+$

This captures a user ID dynamically.

Example Matches

  • /users/123

  • /users/456

Mapping URLs with query parameters

For URLs like /search?q={query}, the regex would be:

^/search?q=[a-zA-Z0-9]+$

Example Matches

  • /search?q=apple

  • /search?q=123abc

Mapping URLs with optional parameters

For a URL pattern like /products/{category}/{id}, where category is optional:

^/products/[a-zA-Z]+?/[0-9]+$

Example Matches

  • /products/123

  • /products/electronics/123

Mapping URLs with a wildcard or multiple paths

For /blog/*:

^/blog/.*?$

Example Matches

  • /blog

  • /blog/how-to-code

  • /blog/2021/10

Mapping URLs with subdomains
For subdomain URLs:

^https?://?[a-zA-Z0-9-]+.example.com$

Example Matches

  • http://blog.example.com

  • https://shop.example.com

Combining multiple components

To handle more complex URL mappings, you can combine the various components as needed. The comprehensive regex that matches a URL with an optional protocol, domain, path, query parameters, and fragment looks like this:

^https?://?[a-zA-Z0-9.-]+/[a-zA-Z0-9/._-]*??[a-zA-Z0-9=&._-]*?#[a-zA-Z0-9_-]*?$

FAQs

How can I remove the Page help and Search bar from the widget when URL mapping for a single article is configured?

To remove the Page help and Search bar from the widget when URL mapping for a single article is configured:

  1. Navigate to Widget () in the Knowledge base portal.

  2. Hover over the desired widget and click the Edit () icon.

  3. Paste the provided code in the Custom CSS tab:

    li#page-help-tab {
    display: none;
}

.article-header .article-back-icon {
    display: none;
}

.search-container {
    display: none !Important;
}

  4. Paste the provided code in the Custom JavaScript tab:

    setTimeout(function() { $('.search-container').hide();}, 2000);
setTimeout(function() { $("#knowledge-base-tab").click();}, 2000);

  5. Click Save.

This will hide the Page help tab and Search bar in the widget on the Knowledge base site when URL mapping for a single article is configured.

How can I see the updates immediately in the KB Widget after adding or updating a URL Map?

The updates are cached on the server for performance reasons and will automatically refresh every 15 minutes. However, if you need to see the changes immediately, you can clear the application cache.

Why does a configured URL mapping appear broken?

The URL mapping would be broken due to any changes in the 'Filter widget content' configuration in the 'Installation & setup' tab. Check the URL mapping and update the configuration.

What is URL mapping?

With URL mapping, you can make specific articles and categories appear in the knowledge base widget, depending on the page the end-user is on. You can also use URL mapping to hide the Knowledge base widget on a specific URL or provide a search bar with a custom placeholder to point end-users in the right direction on what to search.

Can I add regular expressions (regex) in URL mapping?

You can include regular expressions in your URL by enabling the Is Regex toggle.

What is regex?

Regex, short for "regular expression," is a sequence of characters that defines a search pattern used to match and manipulate text strings.

For example, you can use regex to configure a single URL mapping for multiple articles with similar URLs. Consider a scenario where you wish to configure URL mapping for the following articles with the base URL 'https://example.com/docs/drive':

  • https://example.com/drive-General

  • https://example.com/drive-settings

  • https://example.com/drive-functionA

  • https://example.com/drive-functionB

  • https://example.com/drive-functionC

  • https://example.com/drive-functionD

  • https://example.com/drive-functionE

Without regex, you would need to add individual URL mappings for each URL. However, by enabling regex, you can add with a single URL mapping: Select the "Include path" option and add docs/drive in the URL field. You can use regex to have a more efficient and streamlined mapping process.

Can I add URL mapping for categories?

Yes, you can add URL mapping for categories. It applies only to page and index categories.

Related articles