What It Does
The Docs integration connects to the Help Scout Docs API to provide real-time documentation search and browsable knowledge base categories right on your support portal. Visitors can find answers without ever opening a ticket.
How to Enable
- Go to DeskPress > Integrations > Docs.
- Enter your Docs API Key (from your Help Scout account).
- Enter your Docs Site ID (identifies your Docs site).
- Enter your Default Collection ID (the collection to search within by default).
- Save your settings.
Your portal will now have live documentation search and browsable topics.
Configuration Walkthrough
Step 1: Connect to Help Scout Docs
Go to DeskPress > Integrations > Docs and enter your API credentials. You'll find these in your Help Scout account under the Docs section. Once saved, DeskPress can pull articles, collections, and search results from your Docs site.
Step 2: Choose Your Topic Display Mode
Go to DeskPress > Support Portal > Design > Topics and pick how knowledge base categories appear on your portal:
| Mode | What It Does |
|---|---|
| Hardcoded | Displays a fixed set of topic cards with custom icons. The defaults are: Getting Started, Account & Billing, Features & How-To, Integrations, Troubleshooting, and API & Developers. You can customize these. |
| API | Pulls live categories directly from your Help Scout Docs collections. These update automatically when you add or reorganize collections. |
| Both | Combines your hardcoded cards with live API collections. Great if you want a mix of curated and dynamic content. |
Step 3: Set Up Search
Search works out of the box once your Docs API credentials are configured. The portal hero section includes an AJAX-powered search bar that shows results as visitors type (with a 300ms debounce to keep things smooth). Up to 10 results appear per search.
Step 4: Configure Purchase Prioritization (Optional)
If you run an online store with Easy Digital Downloads (EDD) or WooCommerce, you can prioritize documentation for products your customers have purchased.
- Toggle Prioritize Purchased to on.
- Set up the Collection-Product Mapping -- a JSON mapping that links Help Scout Docs collection IDs to your product IDs.
When enabled, collections related to the logged-in user's purchases appear first and are marked with a "Recommended" badge.
Shortcodes
[hsd_docs] -- Displays a full documentation browser with search and optional topic cards. Supports attributes: collection_id, placeholder, and show_topics (set to "false" to hide topic category cards).
[hsd_docs_search] -- Displays a standalone search input for documentation. Supports attributes: collection_id and placeholder.
Use these shortcodes on any page or post where you want to add Docs functionality outside of the main portal.
WordPress Widget
DeskPress includes a "DeskPress - Docs" sidebar widget you can add to any widget area. It's especially useful on product pages.
Widget options:
| Option | Description |
|---|---|
| Title | Widget heading text |
| Collection ID | Which Docs collection to show articles from |
| Placeholder Text | Search bar placeholder |
| Number of Articles | How many articles to display (up to 20) |
| Show Search | Toggle the search bar on or off |
Product page integration: On EDD or WooCommerce product pages, the widget automatically checks for a _hsd_docs_collection_id custom field. If found, it displays documentation specific to that product.
Caching
To keep your portal fast, DeskPress caches Docs data:
- Collections and articles are cached for 1 hour.
- To clear the cache manually, go to DeskPress > Integrations > Docs and use the clear cache option.
This means changes to your Docs site may take up to an hour to appear on your portal unless you clear the cache.
Settings Reference
| Setting | Description |
|---|---|
| Docs API Key | API key for accessing Help Scout Docs |
| Docs Site ID | Your Docs site identifier in Help Scout |
| Default Collection ID | The collection used to filter search results by default |
| Prioritize Purchased | Show collections related to the user's purchased products first (requires EDD or WooCommerce) |
| Collection-Product Mapping | JSON mapping that links Docs collection IDs to product IDs in your store |
Tips and Common Questions
How do I find my Docs API Key and Site ID?
Log in to your Help Scout account, go to the Docs section, and look for your API settings. The Site ID is typically visible in your Docs URL.
Can I use Docs search without the portal?
Yes. Use the [hsd_docs_search] shortcode to add a standalone search bar to any page, or use the sidebar widget in any widget area.
Why don't I see updated articles?
DeskPress caches Docs content for 1 hour. Clear the cache at DeskPress > Integrations > Docs to see changes immediately.
What does "Prioritize Purchased" do exactly?
When a logged-in customer has purchased products from your store, any Docs collections mapped to those products are moved to the top of the topics list and highlighted with a "Recommended" badge. This helps customers find relevant documentation faster.
How many search results appear?
The search bar shows up to 10 results. Results appear as the visitor types, with a short delay to avoid unnecessary requests.
Can I show different documentation for different products?
Yes. Use the _hsd_docs_collection_id custom field on your product pages. The Docs widget will automatically display articles from the specified collection when viewing that product.