Hubspot -> raia Agent

As a user of Raia Agent, I want to automatically sync our HubSpot Knowledge Base articles into a Raia Agent as a Markdown file. This will provide the agent with our support documentation, enabling it to answer customer questions.

Important Note on HubSpot API Limitations:

HubSpot does not provide a dedicated API for its Knowledge Base. It is not possible to programmatically list, create, read, or update articles directly. This task must work around this limitation by using the CMS Site Search API, which can search for knowledge base articles but cannot guarantee a complete retrieval of all articles.

Proposed Workflow (Primary Approach):

The n8n workflow should run on a nightly schedule and perform the following actions:

1. Search for Knowledge Base Articles: Use the HubSpot Site Search API to find knowledge base articles. This will likely require using a broad search query to maximize the number of results.

2. Filter and Retrieve Content: Filter the search results to include only content of type KNOWLEDGE_ARTICLE. For each result, use the indexed-data endpoint to retrieve the full content.

3. Consolidate to Markdown: Convert the fetched articles into a single, well-structured Markdown file. The file should include the article title, its URL, and the body content.

4. Upload to Raia Agent: Upload the generated Markdown file to the Raia Agent using the API.

Acceptance Criteria:

• An n8n workflow is created that uses the HubSpot Site Search API to find and retrieve knowledge base articles.

• The workflow consolidates the retrieved articles into a single Markdown file.

• The workflow successfully uploads the Markdown file to the Raia Agent via the API.

• The workflow is scheduled to run every night.

• The workflow includes robust error handling and notifications, especially for cases where the search API returns incomplete results.

• The limitations of this approach are documented within the workflow.

Technical Details:

• HubSpot API (Site Search):

  • Authentication: HubSpot API Key or OAuth Token.

  • Search Endpoint: GET https://api.hubapi.com/cms/v3/site-search/search?type=KNOWLEDGE_ARTICLE&q={search_term}

  • Get Content Endpoint: GET https://api.hubapi.com/cms/v3/site-search/indexed-data/{contentId}

• Raia Agent API:

  • Endpoint: POST /external/agent-files/upload

  • Request Type: multipart/form-data

  • Authentication: API Key in the header.

  • Request Body:

    • file: The Markdown file to upload.

    • autoAddToVectorStore: true.

Alternative Approaches (to be considered if the primary approach is insufficient):

• Web Scraping: If the Site Search API does not provide complete results, a web scraping solution could be developed to crawl the public knowledge base and extract articles.

• Manual Export: Investigate if HubSpot allows for a manual export of knowledge base articles. If so, the n8n workflow could be designed to process this exported file.

Implementation Notes:

• The developer must be aware that a 100% complete sync of all articles may not be achievable through the API alone.

• The search query used in the Site Search API call should be carefully chosen to be as broad as possible.

• The workflow should be tested to determine the completeness of the results from the Site Search API.