--- title: "URL mapping in Knowledge base Widget | Document360" slug: "url-mapping" description: "With the Knowledge base assistant, you can display specific articles depending on the page the end-user is on with Document360's URL mapping feature. " tags: ["contextual help", "Knowledge base widget", "Premium"] updated: 2026-08-25T07:15:48Z published: 2026-08-25T07:15:48Z canonical: "docs.document360.com/url-mapping" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.document360.com/llms.txt > Use this file to discover all available pages before exploring further. # URL Mapping URL mapping lets you configure what the Knowledge base widget displays on a page-by-page basis. For each URL on your website or application, you can show a specific article, a category list, a search bar with a custom placeholder, or hide the widget entirely. This makes the widget context-aware — users see the most relevant help content based on where they are in your product. CAUTION 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](https://docs.document360.com/help/docs/installing-the-knowledge-base-widget). --- ## When to use URL mapping - Surface a specific article directly in the widget on a page where users frequently need it. - Show a curated list of articles from a category when a user is in a specific product module. - Hide the widget on pages where it should not appear (e.g. login pages, checkout flows). - Display a custom search placeholder to guide users on what to search for in a given context. - Use AI-powered contextual assistance (page-level prompting) for specific URLs. --- ## Before you begin The content you want to map (articles or categories) must fall within the widget's configured [content access](https://docs.document360.com/docs/content-access-for-the-knowledge-base-widget) scope. --- ## Actions There are five actions you can execute with URL mapping: | Action | What it does | | --- | --- | | **Show article** | Displays a single article on the specified URL | | **Show list of articles** | Lists selected articles under the Recommended section within the widget on the specified URL | | **Contextual AI assistance** | Allows you to create and use AI-powered prompts within the widget | | **Show search results** | Sets a specific search term to query your knowledge base, returning relevant results on the specified URL | | **Hide widget** | Prevents the widget icon from appearing on the specified URL | NOTE The **Show list of articles** action displays content in the Most searched articles section of the widget. If the **Hide most searched articles** toggle is enabled in widget settings, this section will be hidden and the mapped article list will not appear. Ensure this setting is turned off for URL mapping to work as expected. --- ## URL parameters When configuring the widget URL, you can include three types of parameters: - **Include Path**: `/thisis/a/path` - **Include Query**: `?animal=bear` - **Include Hash**: `#inbox` You can also enable the **Is Regex** toggle to incorporate regular expressions into your URL configurations. --- ## Add a URL mapping ![Animated walkthrough showing how to add a URL mapping in the knowledge base widget](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/url%20mapping%20widget.gif) 1. In the left navigation bar, navigate to **Connections** () > **Knowledge base widget**. 2. Hover over the desired widget and click **Edit** (). 3. Click the **URL mapping** tab. 4. Click **New URL mapping** and specify the following: - **Name** — The URL mapping name is shown only 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. Enter the URL on which you want the article or action to appear. NOTE Your domain name is *not* included in the URL path. For example, for `https://document360.com/ebook/rapid-guide/`, the URL path would be `/ebook/rapid-guide/`. - **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). NOTE A single URL mapping is associated with only one language at a time. If you map a second language to the same URL, the earlier mapping for that URL is replaced, not combined. If your application uses the same URL regardless of the selected language (the URL does not change when a user switches language in your app), you cannot map multiple languages to it. To display language-specific articles, use a distinct URL per language (for example, a language-specific path or parameter) and create a separate mapping for each. - **Article to show** — In the search bar, select the articles or categories you want to show. NOTE Folder categories are not available for selection. Only **page** and **index** category types are available. 5. Click **Create**. Once an end user accesses the specified URL and opens the widget, they will see the mapped article or category. This content is retained as they navigate between the widget tabs within the same version and language. --- ## Editing URL mappings 1. Navigate to **Connections** () > **Knowledge base widget**. 2. Hover over the desired widget and click **Edit** (). 3. In the **URL mapping** tab, find the list of available mappings. 4. Hover over the desired mapping and click **Edit** (). 5. The **Update URL mapping** panel appears. 6. Update the desired information and click **Update**. --- ## Deleting URL mappings 1. Navigate to **Connections** () > **Knowledge base widget**. 2. Hover over the desired widget and click **Edit** (). 3. In the **URL mapping** tab, find the list of available mappings. 4. Hover over the desired mapping and click **Delete** (). 5. Click **Yes** in the **Delete confirmation** prompt. --- ## URL mapping settings (default behavior) You can define the widget's behavior for URLs that have no configured mapping. ![URL mapping settings panel showing the two default behavior options](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/url%20mapping%20settings%20new.png) 1. Navigate to **Connections** () > **Knowledge base widget**. 2. Hover over the desired widget and click **Edit** (). 3. Click the **Advanced settings** tab. 4. Expand the **URL mapping settings** section. 5. Select the desired option: - **Navigate to the page help/knowledge base** — Display the article or category in the Page help or Knowledge base tab in the widget. - **Do not make any changes to the existing setup** — Display the last opened article or category in the widget. 6. Click **Save**. --- ## Configuring contextual AI assistance The **Contextual AI assistance** action lets you display AI-powered prompts in the widget based on page context. Prompts can appear when users click a button or automatically when they open a specific page. ![Widget configuration interface showing URL mapping and contextual AI assistance options](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/contextual%20AI%20assistance%20new.png) NOTE To configure Contextual AI assistance, ensure that AI assistive search is enabled for the widget. You can configure Contextual AI assistance in two ways: - **Button-based prompting** — Displays context-aware help when readers click specific buttons on your website or app. - **Page-level prompting** — Provides AI-driven help automatically when users open a specific page, without requiring button interaction. ### Button-based prompting Each prompt you add generates a unique **Trigger key**. The prompt is automatically validated on pressing Enter to confirm whether an answer is found in your connected sources. You can configure up to 5 button–prompt mappings per URL. ![Configuration options for contextual AI assistance showing button-based prompting setup](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/button%20based%20prompting.png) 1. In the **Configure contextual AI assistance** section, leave the **Enable page-level prompting** checkbox unchecked. 2. Enter your **Search prompt**. 3. Press **Enter** to validate. - If an answer is found, a green **Answer found** label appears. - If no answer is found, a red **Answer not found** label appears. 4. If updating an existing button, copy the **Trigger key** and add it to the button's code using the `d360AIHelp` attribute: ![Instructions for adding URL mapping and contextual AI assistance in a widget interface](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/trigger%20key%20info.png) ``` ``` 1. If creating a new button, click **Copy code** next to Installation code and paste the snippet into your page's HTML. ![Instructions for configuring contextual AI assistance with a widget installation code](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/copy%20code%20info.png) 1. To add another prompt, click **Add more** and repeat. To remove a prompt, click **Remove**. ### Page-level prompting ![Configuration options for a widget including page-level prompting settings](https://cdn.document360.io/860f9f88-412e-4570-8222-d5bf2f4b7dd1/Images/Documentation/button%20based%20prompting.png) 1. Select the **Enable page-level prompting** checkbox. 2. In the **Search prompt** field, enter your query. 3. Press **Enter** to validate the prompt. - Green **Answer found** = answer available. - Red **Answer not found** = no match. 4. To add another prompt, click **Add more**. You can add up to 5 prompts per URL. - The first prompt appears as the primary question. - Remaining prompts appear as suggested queries. 5. To delete a prompt, click **Remove** beside it. Once configured, 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. --- ## Using regex in URL mapping Understanding URL matching is important for effective URL mapping. Enable the **Is Regex** toggle when adding or editing a mapping to use regular expressions. ### Common regex patterns | URL structure | Regex configuration | | --- | --- | | `/buckets` | `/buckets$` (matches URLs ending with `buckets`) | | `/buckets?isCreatingBucket` | `/buckets\?[a-z]*` (matches URLs with random text after query parameter) | **Map a URL pattern like `/users/{id}`:** ``` ^/users/[0-9]+$ ``` **Map `/blog/*` (wildcard):** ``` ^/blog/.*?$ ``` **Map `/search?q={query}`:** ``` ^/search?q=[a-zA-Z0-9]+$ ``` **Map subdomain URLs:** ``` ^https?://?[a-zA-Z0-9-]+.example.com$ ``` NOTE When testing your URL regex on [https://regex101.com](https://regex101.com), add a backward slash (`\`) before every forward slash (`/`). --- ## Considerations - URL mappings must use content **within the widget's content access scope**. If the scope changes, existing mappings may be invalidated. - Configuration changes are cached for up to **15 minutes**. Clear the application cache to see changes immediately. NOTE The **Hide most searched articles** toggle, if enabled, also disables URL-based article list mapping. If you use URL mapping to surface category lists, keep that toggle off. --- ## Best practices - Map your most-visited support pages first — analytics will show you where users most frequently search for help. - Use the **Hide** action on high-friction pages (login, payment, first-time setup) where the widget would distract rather than help. - Use **Is Regex** for pattern-based mappings that need to cover multiple similar URLs. --- ## FAQ **What is URL mapping?** URL mapping lets you control what the knowledge base widget displays — or whether it appears at all — on specific pages of your website or application. You can map articles, category lists, a search bar, or hide the widget for any URL. **Why does a configured URL mapping appear broken?** This typically happens when the widget's **Content access** filter has been changed. If the filter no longer includes the workspace or category used in the mapping, the mapping becomes invalid. Check the content access settings and update or recreate the mapping. **How can I see URL mapping changes immediately without waiting 15 minutes?** Widget configuration is cached for 15 minutes for performance. To see changes immediately, clear the application cache in your browser or your web application's cache layer. **Can I add regular expressions (regex) in URL mapping?** Yes. Enable the **Is Regex** toggle when adding or editing a URL mapping to use regular expression patterns. Regex allows a single mapping to cover multiple similar URLs. **Can I add URL mapping for categories?** Yes. URL mapping supports categories — it applies only to page and index category types. Folder categories are not available for selection. **How can I remove the Page help tab and Search bar from the widget when URL mapping for a single article is configured?** Navigate to **Connections > Knowledge base widget > Edit**. Paste the following in the **Custom CSS** tab: ``` li#page-help-tab { display: none; } ``` Then paste the following in the **Custom JavaScript** tab and click **Save**: ``` setTimeout(function() { $('.search-container').hide(); }, 2000); setTimeout(function() { $("#knowledge-base-tab").click(); }, 2000); ``` This hides the Page help tab and Search bar in the widget when URL mapping for a single article is configured. **What is regex?** Regex (regular expression) is a sequence of characters that defines a search pattern used to match and manipulate text strings. In URL mapping, enabling regex lets you configure a single mapping to cover multiple URLs with similar patterns. For example, instead of adding individual mappings for `https://example.com/drive-General`, `https://example.com/drive-settings`, and so on, you can use `docs/drive` with the Include path option to match all of them in one mapping. ## Related - [Installing the Knowledge base widget](/installing-the-knowledge-base-widget.md) - [Eddy AI Assistant for widget](/knowledge-base-widget-getting-started.md) - [Edit, Clone, and Delete widget](/edit-clone-and-delete.md)