Freshdesk Knowledge Sync

Overview

This guide will help you set up the Freshdesk integration with Brainfish to import your help center articles and knowledge base content. The integration allows you to sync articles from your Freshdesk help center categories and folders into Brainfish for enhanced search and AI-powered assistance.

Prerequisites

Before you begin, ensure you have:

1. Freshdesk Account: An active Freshdesk account with admin access
2. Help Center Content: Articles published in your Freshdesk help center

Step 1: Get Your Freshdesk API Key

Method 1: From Freshdesk Admin Panel (Recommended)

1. Log into your Freshdesk account
   • Go to https://yourcompany.freshdesk.com
   • Replace yourcompany with your actual Freshdesk subdomain
2. Navigate to Profile Settings
   • Click on your profile picture in the top-right corner
   • Select "Profile Settings" from the dropdown menu
3. Access API Settings
   • In the left sidebar, click on "API"
   • You'll see a section titled "API Key"
4. Generate or Copy API Key
   • If you don't have an API key, click "Generate API Key"
   • If you already have one, click "Show" to reveal it
   • Copy the API key - you'll need this for the next step

Method 2: From Freshdesk Developer Hub

1. Visit Freshdesk Developer Hub
   • Go to https://developers.freshdesk.com
   • Sign in with your Freshdesk credentials
2. Access API Documentation
   • Navigate to "API Reference" → "Help Desk API"
   • Look for the "Authentication" section
3. Find Your API Key
   • Your API key will be displayed in the authentication examples
   • Copy it for use in Brainfish

Step 2: Identify Your Freshdesk Domain

Your Freshdesk domain is the subdomain part of your Freshdesk URL:

• URL Format: https://yourcompany.freshdesk.com
• Domain to Use: yourcompany (just the subdomain part)

Examples:

• If your Freshdesk URL is https://acme.freshdesk.com, use acme
• If your Freshdesk URL is https://support.mycompany.freshdesk.com, use support.mycompany

Step 3: Set Up Integration in Brainfish

1. Access Knowledge Section

1. Log into your Brainfish account
2. Navigate to the "Knowledge" section in the left sidebar
3. Click "Add Source" or "New Source"

2. Select Freshdesk

1. In the source type selector, choose "Freshdesk"
2. You'll see the Freshdesk configuration panel

3. Configure Integration

1. Enter API Key

   • Paste your Freshdesk API key in the "Freshdesk API Key" field
   • The system will validate the key automatically

2. Enter Domain

   • In the "Freshdesk Domain" field, enter only your subdomain
   • Example: If your URL is https://acme.freshdesk.com, enter acme
   • Important: Don't include https:// or .freshdesk.com

3. Select Categories (Optional)

   • Once your credentials are validated, you'll see a list of available categories
   • You can select specific categories or leave it as "All Categories" to sync everything
   • Categories cannot be changed after the initial setup

   

4. Configure Sync Settings

1. Enable Daily Sync (Recommended)
   • Toggle "Enable daily sync" to automatically keep your content up-to-date
   • This will sync your Freshdesk content daily at 2:00 AM UTC
2. Save Configuration
   • Click "Save" to create your Freshdesk integration

Step 4: Verify Integration

Check Initial Sync

1. After saving, the system will begin the initial sync
2. You can monitor the progress in the Knowledge section
3. The sync may take several minutes depending on the amount of content

Verify Content

1. Once sync is complete, your Freshdesk articles will appear in Brainfish
2. You can search for your content using Brainfish's search functionality
3. The content will be available for AI-powered assistance and recommendations

Troubleshooting

Common Issues

1. "Invalid Freshdesk credentials" Error

Possible Causes:

• Incorrect API key
• Wrong domain format
• API key doesn't have sufficient permissions

Solutions:

• Double-check your API key in Freshdesk Admin Panel
• Ensure you're using only the subdomain (e.g., acme, not acme.freshdesk.com)
• Verify your API key has access to the help center content

2. "Domain not found" Error

Possible Causes:

• Incorrect subdomain
• Freshdesk account doesn't exist
• Network connectivity issues

Solutions:

• Verify your Freshdesk URL and extract the correct subdomain
• Check that your Freshdesk account is active
• Ensure your network can access Freshdesk

3. "SSL handshake failed" Error

Possible Causes:

• Network restrictions or firewall settings
• SSL/TLS configuration issues

Solutions:

• Check your network/firewall settings
• Try from a different network if possible
• Contact your IT department if using corporate network

4. "Request timeout" Error

Possible Causes:

• Large amount of content to sync
• Network latency
• Freshdesk API rate limits

Solutions:

• The system will automatically retry with exponential backoff
• For large instances, the initial sync may take longer
• Consider selecting specific categories instead of all content

5. No Categories Available

Possible Causes:

• No help center content published
• API key doesn't have access to help center
• Help center not enabled in Freshdesk

Solutions:

• Ensure you have published articles in your Freshdesk help center
• Check that your API key has the necessary permissions
• Verify help center is enabled in your Freshdesk account

API Key Permissions

Your Freshdesk API key needs the following permissions:

• Read access to help center articles
• Read access to categories and folders
• Read access to article content and metadata

Rate Limiting

Freshdesk has API rate limits to prevent abuse. The Brainfish integration:

• Automatically handles rate limiting with delays between requests
• Retries failed requests with exponential backoff
• Provides detailed error messages for rate limit issues