HubSpot Knowledge Base

Import knowledge base articles from HubSpot Service Hub

Import articles from HubSpot Service Hub into AGO as knowledge sources.

Overview

The HubSpot Knowledge Base connector allows you to import content from HubSpot Service Hub Knowledge Base, including:

• Categories: Organizational groupings for articles
• Articles: Individual knowledge base articles with rich HTML content

The connector converts HTML content to Markdown format and preserves the hierarchical category-article structure.

Note: This connector imports from HubSpot’s Knowledge Base (Service Hub). For HubSpot ticketing integration, see HubSpot Ticketing.

Features

• Article Import: Fetch published, draft, or all articles
• Category Support: Import category hierarchy
• HTML to Markdown Conversion: Automatically converts article HTML to Markdown
• Hierarchical Structure: Preserves category-article parent-child relationships
• Category Filtering: Import only specific categories by ID
• State Filtering: Filter articles by publication state (Published, Draft, All)
• Incremental Updates: Version-controlled imports with deduplication

Prerequisites

HubSpot Requirements

1. Service Hub Professional or Enterprise: The Knowledge Base feature requires a paid Service Hub tier
2. Private App: Create a private app with the required API scope
3. Scope: cms.knowledge_base.articles.read

Creating a HubSpot Private App

1. In HubSpot, go to Settings > Integrations > Private Apps
2. Click Create a private app
3. Enter a name (e.g., AGO Knowledge Base)
4. Go to the Scopes tab
5. Under CMS, enable: cms.knowledge_base.articles.read
6. Click Create app
7. Copy the Access Token (store it securely)

Finding Your Portal ID

Your Portal ID appears in your HubSpot URL:

https://app.hubspot.com/contacts/12345678/...
                              ^^^^^^^^
                              This is your Portal ID

Configuration

Knowledge Source Setup

Create a new Knowledge Source with the following configuration:

1. Navigate to Knowledge > Sources > Add Source
2. Select HubSpot Knowledge Base as the source type
3. Enter a name (e.g., “My HubSpot Knowledge Base”)
4. Paste your Private App access token
5. Configure the import options described below
6. Click Save

Configuration Parameters

Parameter	Type	Required	Description
portal_id	string	No	HubSpot portal ID for constructing external links
knowledge_base_domain	string	No	Custom domain for external knowledge base links
import_categories	boolean	No	Whether to import category documents (default: true)
import_articles	boolean	No	Whether to import article documents (default: true)
category_filter	array	No	List of category IDs to import (empty = import all)
state_filter	string	No	Article state: PUBLISHED, DRAFT, or empty for all (default: PUBLISHED)

Usage Examples

Import Only Published Articles

{
  "additional_info": {
    "portal_id": "12345678",
    "import_categories": true,
    "import_articles": true,
    "state_filter": "PUBLISHED"
  }
}

Import Specific Categories

Import only articles from selected categories:

{
  "additional_info": {
    "portal_id": "12345678",
    "category_filter": ["cat_123", "cat_456"],
    "state_filter": "PUBLISHED"
  }
}

Import All Content Including Drafts

{
  "additional_info": {
    "portal_id": "12345678",
    "state_filter": ""
  }
}

Content Processing

HTML to Markdown Conversion

Article content is automatically converted from HTML to Markdown:

• Headings are converted to ATX format (# Heading)
• Lists, links, and formatting are preserved
• The article title is prepended as a top-level heading

Metadata Preservation

Each imported document retains key properties from HubSpot:

Property	Applies To	Description
Type	Categories, Articles	Whether the imported item is a category or article
Position	Categories, Articles	Sort order within the parent group
Created / Updated dates	Categories	Original timestamps from HubSpot
Category	Articles	The parent category name and association
Publication state	Articles	Whether the article is Published or Draft
Path	Articles	The URL path of the article in HubSpot

Hierarchical Structure

The connector preserves the HubSpot Knowledge Base hierarchy:

Articles without a matching category are imported as top-level documents.

Error Handling

The connector includes error handling for common scenarios:

• Invalid credentials: Clear error messages for authentication failures
• Missing content: Skips articles that fail to process without stopping the import
• Categories endpoint unavailable: Falls back gracefully if the categories REST endpoint returns 404
• Rate limiting: HubSpot private apps are limited to 100 requests per 10 seconds

Best Practices

Improving Sync Speed

1. Filter Content: Use category and state filters for large knowledge bases
2. Published Only: Import only published articles unless drafts are needed
3. Incremental Updates: Version IDs track import iterations automatically

Content Management

1. Regular Syncs: Schedule periodic imports to capture content updates
2. Review Content: Check imported documents for formatting issues after initial import
3. Category Organization: Use HubSpot categories to organize content before import

Security

1. Private App Security: Use a dedicated private app with minimal scopes
2. Token Rotation: Rotate private app tokens periodically
3. Scope Limitation: Only grant cms.knowledge_base.articles.read scope

Troubleshooting

Common Issues

Authentication Errors:

• Verify the private app access token is correct and not revoked
• Ensure the private app has the cms.knowledge_base.articles.read scope
• Check that your HubSpot account has Service Hub Professional or Enterprise

No Articles Imported:

• Verify articles exist in your HubSpot Knowledge Base
• Check that the state_filter matches your articles’ publication state
• Ensure category_filter IDs are correct (if set)

Categories Not Imported:

• The categories REST endpoint may not be available in all HubSpot tiers
• The connector falls back gracefully; articles are still imported without category hierarchy

Missing External Links:

• Provide a portal_id in the configuration to enable external link generation
• External links use the format https://app.hubspot.com/knowledge/{portal_id}/articles/{path}

---

Related Documentation

• HubSpot Ticketing - HubSpot ticketing integration
• Knowledge Connectors - All available knowledge connectors
• Knowledge Source Management - Source configuration
• Zendesk Integration - Similar help center connector