Zendesk Knowledge Sync

Integrate your team's knowledge directly from Zendesk into Brainfish. By syncing your Zendesk help center articles, you can keep your AI agent's knowledge up-to-date automatically, ensuring it always provides the most accurate and relevant answers based on your customer support documentation.

This guide will walk you through the process of connecting and syncing your Zendesk help center as a knowledge source.

Step 1: Navigate to Knowledge and Connect a New Data Source

1. From your Brainfish Dashboard, click on Knowledge in the left-hand navigation menu.
2. Click the + Connect data source button.
3. From the list of external data sources, select Zendesk.

Step 2: Configure Your Zendesk Connection

You will now see the "Configure Zendesk" form. You'll need to provide a name for this source and your Zendesk credentials.

Source Name: Enter a descriptive name for your connection, such as "Customer Support Docs" or "Help Center Articles".

How to Find Your Zendesk Domain

1. From Your Zendesk URL
   • Look at your browser's address bar when you're logged into Zendesk.
   • Your full Zendesk URL looks like https://acme.zendesk.com — the part you need is just the subdomain (acme).
2. From Zendesk Admin Panel
   • Go to Admin Center → Account → Account settings.
   • Look for Subdomain in the account information — this is your Zendesk domain.
3. Common examples
   • https://acme.zendesk.com → enter acme
   • https://help.acme.zendesk.com → enter help.acme
   • https://support.acme.zendesk.com → enter support.acme

Zendesk API Token: To get your API token, you'll need to generate one in your Zendesk account.

Method 1: From Zendesk Admin Panel (Recommended)

1. Log into your Zendesk account
   • Go to https://yourcompany.zendesk.com and sign in with your admin credentials.
2. Navigate to Admin Settings
   • Click on the Admin icon (gear icon) in the left sidebar.
   • Select Channels from the admin menu.
   • Click on API in the submenu.
3. Enable Token Access
   • In the API settings, you'll see a section for Token Access.
   • Click Edit next to Token Access.
   • Toggle the switch to Enabled and click Save.
4. Generate API Token
   • Go to Admin Center → People → Team members.
   • Find your user account and click on it.
   • In the Channels section, click Edit next to API.
   • Click Add API token, give it a descriptive name (e.g., "Brainfish Integration"), and click Save.
   • Copy the token immediately — Zendesk won't show it again.

Method 2: From User Profile Settings

1. Access Your Profile
   • Click on your profile picture in the top-right corner.
   • Select View profile.
2. Navigate to API Settings
   • In your profile, click on API in the left sidebar.
   • You'll see your existing API tokens or an option to create a new one.
3. Create New Token
   • Click Add API token.
   • Name your token (e.g., "Brainfish Knowledge Base").
   • Click Generate and copy the token.

Method 3: From Developer Hub (Alternative)

1. Access Developer Hub
   • Go to https://developer.zendesk.com.
   • Sign in with your Zendesk account.
2. Create Integration
   • Click Create integration.
   • Select Private app.
   • Give your app a name (e.g., "Brainfish Integration").
3. Configure Permissions
   • In the Permissions section, add the following scopes:
     • read access to Help Center (articles, categories, sections)
     • read access to Users (for author attribution on articles)
   • Click Create.
4. Get API Token
   • After creation, you'll see your API Token.
   • Copy this token for use in Brainfish.

Agent Email: Enter the email address of the Zendesk agent account that will be used for API access. This should be the same email associated with the API token you just created.

How to Find Your Agent Email

1. Use Your Admin Email (Recommended)
   • Use the email address you use to log into Zendesk.
   • This ensures the integration has access to all help center content.
   • You can find this in your profile settings.
2. From Your Profile Settings
   • Click on your profile picture in the top-right corner.
   • Select View profile.
   • Your email address will be displayed in the Email field.
3. From Admin Panel
   • Go to Admin Center → People → Team members.
   • Find your user account in the list.
   • Click on your name to view your profile.
   • The email address will be shown in your user details.
4. Create a Dedicated User (Optional)
   • If you prefer, you can create a dedicated Zendesk user account for the integration.
   • Go to Admin Center → People → Team members.
   • Click Add user.
   • Create a new agent account with a descriptive name (e.g., "Brainfish Integration").
   • Use this account's email address as the agent email.
   • Ensure this user has access to the help center content.

Paste the API Token: Return to Brainfish and paste the copied token into the Zendesk API Token field.

Select Locale (Optional): If your help center supports multiple languages, select the locale you want to sync. Leave as "All" to sync all available locales.

Click the + Add Source button to finalize the connection.

Step 3: Sync and Verify Your Content

After adding the source, Brainfish will begin importing content from your Zendesk help center.

1. On the Knowledge page, you will see your new Zendesk source with a "Syncing" status. This process may take a few minutes, depending on the amount of content.
2. Once the sync is complete, the status will update to show the number of articles imported.
3. Click on the newly created Zendesk catalog to view the list of imported articles. You can click the eye icon (👁️) next to any article to preview its content and ensure it was imported correctly.

Step 4: Enable the Source for Your Agent

To start using this knowledge, you must enable the source and ensure your agent has access to it.

1. On the Knowledge page, find your new Zendesk catalog card. Click the three-dots menu (...) and ensure the source is Enabled.
2. Navigate to the Agents page from the left-hand menu.
3. Select the agent you want to train with this new knowledge.
4. In the agent configuration panel, go to Knowledge Settings.
5. Ensure that All sources is selected, or specifically add your new Zendesk source from the dropdown menu.

Step 5: Test Your Integration

Finally, test that your agent can find and use information from the new source.

1. Open the Agent Playground or your website where the agent is deployed.
2. Ask a question related to the content in your synced Zendesk help center.
3. The agent should provide a detailed answer based on the information from your Zendesk articles. You can also expand the Sources to see the specific Zendesk article that was used to generate the answer.

You have now successfully synced your Zendesk help center with Brainfish! Your agent will now be able to answer questions using the knowledge stored in your Zendesk documentation.

Troubleshooting

Common Issues

"Invalid Zendesk credentials" error

• Verify your API token is correct and hasn't expired.
• Ensure the agent email matches the account associated with the API token.
• Check that your Zendesk domain is correct (just the subdomain, not the full URL).

"Domain not found" error

• Confirm your Zendesk subdomain is correct.
• Ensure your Zendesk account is active and accessible.
• Check for any typos in the domain name.

"SSL handshake failed" error

• This may be due to network restrictions or firewall settings.
• Contact your IT team if you're behind a corporate firewall.
• Try accessing your Zendesk help center directly to verify connectivity.

"Request timeout" error

• The sync process may take longer for large help centers.
• Check your internet connection.
• Try again during off-peak hours.

Best Practices

1. Regular Syncs: Set up regular sync schedules to keep your knowledge base current.
2. Content Organization: Organize your Zendesk articles into clear categories and folders for better organization in Brainfish.
3. API Token Security: Keep your API tokens secure and rotate them periodically.
4. Monitor Usage: Check your Zendesk API usage to ensure you stay within rate limits.

Support

If you encounter any issues during setup, please contact our support team with:

• Your Zendesk domain
• The specific error message you're seeing

Integrate your team's knowledge directly from Zendesk into Brainfish. By syncing your Zendesk help center articles, you can keep your AI agent's knowledge up-to-date automatically, ensuring it always provides the most accurate and relevant answers based on your customer support documentation.

This guide will walk you through the process of connecting and syncing your Zendesk help center as a knowledge source.

Step 1: Navigate to Knowledge and Connect a New Data Source

1. From your Brainfish Dashboard, click on Knowledge in the left-hand navigation menu.
2. Click the + Connect data source button.
3. From the list of external data sources, select Zendesk.

Step 2: Configure Your Zendesk Connection

You will now see the "Configure Zendesk" form. You'll need to provide a name for this source and your Zendesk credentials.

Source Name: Enter a descriptive name for your connection, such as "Customer Support Docs" or "Help Center Articles".

Zendesk Domain: This is your Zendesk subdomain. For example, if your Zendesk URL is https://yourcompany.zendesk.com, your domain would be yourcompany.

How to Find Your Zendesk Domain

1. From Your Zendesk URL
   • Look at your browser's address bar when you're logged into Zendesk
   • Your URL will be in the format: https://yourcompany.zendesk.com
   • The domain is the part before .zendesk.com (e.g., yourcompany)
2. From Zendesk Admin Panel
   • Go to Admin Center → Account → Account settings
   • Look for "Subdomain" in the account information
   • This is your Zendesk domain
3. Common Examples
   • If your URL is https://acme.zendesk.com, use acme
   • If your URL is https://support.mycompany.zendesk.com, use support.mycompany
   • If your URL is https://help.ourbusiness.zendesk.com, use help.ourbusiness

Zendesk API Token: To get your API token, you'll need to generate one in your Zendesk account.

Method 1: From Zendesk Admin Panel (Recommended)

1. Log into your Zendesk account
   • Go to your Zendesk instance (e.g., https://yourcompany.zendesk.com)
   • Sign in with your admin credentials
2. Navigate to Admin Settings
   • Click on the "Admin" icon (gear icon) in the left sidebar
   • Select "Channels" from the admin menu
   • Click on "API" in the submenu
3. Enable Token Access
   • In the API settings, you'll see a section for "Token Access"
   • Click "Edit" next to Token Access
   • Toggle the switch to "Enabled"
   • Click "Save"
4. Generate API Token
   • Go to Admin Center → People → Team members
   • Find your user account and click on it
   • In the Channels section, click "Edit" next to API
   • Click "Add API token"
   • Give your token a descriptive name (e.g., "Brainfish Integration")
   • Click "Save"
   • Copy the token immediately - you won't be able to see it again

Method 2: From User Profile Settings

1. Access Your Profile
   • Click on your profile picture in the top-right corner
   • Select "View profile"
2. Navigate to API Settings
   • In your profile, click on "API" in the left sidebar
   • You'll see your existing API tokens or an option to create a new one
3. Create New Token
   • Click "Add API token"
   • Name your token (e.g., "Brainfish Knowledge Base")
   • Click "Generate" and copy the token

Method 3: From Developer Hub (Alternative)

1. Access Developer Hub
   • Go to https://developer.zendesk.com
   • Sign in with your Zendesk account
2. Create Integration
   • Click "Create integration"
   • Select "Private app"
   • Give your app a name (e.g., "Brainfish Integration")
3. Configure Permissions
   • In the "Permissions" section, add:
     • read access to Help Center
     • read access to Users
   • Click "Create"
4. Get API Token
   • After creation, you'll see your "API Token"
   • Copy this token for use in Brainfish

Agent Email: Enter the email address of the Zendesk agent account that will be used for API access. This should be the same email associated with the API token you just created.

How to Find Your Agent Email

1. Use Your Admin Email (Recommended)
   • Use the email address you use to log into Zendesk
   • This ensures the integration has access to all help center content
   • You can find this in your profile settings
2. From Your Profile Settings
   • Click on your profile picture in the top-right corner
   • Select "View profile"
   • Your email address will be displayed in the "Email" field
3. From Admin Panel
   • Go to Admin Center → People → Team members
   • Find your user account in the list
   • Click on your name to view your profile
   • The email address will be shown in your user details
4. Create a Dedicated User (Optional)
   • If you prefer, you can create a dedicated Zendesk user account for the integration
   • Go to Admin Center → People → Team members
   • Click "Add user"
   • Create a new agent account with a descriptive name (e.g., "Brainfish Integration")
   • Use this account's email address as the agent email
   • Ensure this user has access to the help center content

Paste the API Token: Return to Brainfish and paste the copied token into the Zendesk API Token field.

Select Locale (Optional): If your help center supports multiple languages, select the locale you want to sync. Leave as "All" to sync all available locales.

Click the + Add Source button to finalize the connection.

Step 3: Sync and Verify Your Content

After adding the source, Brainfish will begin importing content from your Zendesk help center.

1. On the Knowledge page, you will see your new Zendesk source with a "Syncing" status. This process may take a few minutes, depending on the amount of content.
2. Once the sync is complete, the status will update to show the number of articles imported.
3. Click on the newly created Zendesk catalog to view the list of imported articles. You can click the eye icon (👁️) next to any article to preview its content and ensure it was imported correctly.

Step 4: Enable the Source for Your Agent

To start using this knowledge, you must enable the source and ensure your agent has access to it.

1. On the Knowledge page, find your new Zendesk catalog card. Click the three-dots menu (...) and ensure the source is Enabled.
2. Navigate to the Agents page from the left-hand menu.
3. Select the agent you want to train with this new knowledge.
4. In the agent configuration panel, go to Knowledge Settings.
5. Ensure that All sources is selected, or specifically add your new Zendesk source from the dropdown menu.

Step 5: Test Your Integration

Finally, test that your agent can find and use information from the new source.

1. Open the Agent Playground or your website where the agent is deployed.
2. Ask a question related to the content in your synced Zendesk help center.
3. The agent should provide a detailed answer based on the information from your Zendesk articles. You can also expand the Sources to see the specific Zendesk article that was used to generate the answer.

You have now successfully synced your Zendesk help center with Brainfish! Your agent will now be able to answer questions using the knowledge stored in your Zendesk documentation.

Troubleshooting

Common Issues

"Invalid Zendesk credentials" error

• Verify your API token is correct and hasn't expired
• Ensure the agent email matches the account associated with the API token
• Check that your Zendesk domain is correct (just the subdomain, not the full URL)

"Domain not found" error

• Confirm your Zendesk subdomain is correct
• Ensure your Zendesk account is active and accessible
• Check for any typos in the domain name

"SSL handshake failed" error

• This may be due to network restrictions or firewall settings
• Contact your IT team if you're behind a corporate firewall
• Try accessing your Zendesk help center directly to verify connectivity

"Request timeout" error

• The sync process may take longer for large help centers
• Check your internet connection
• Try again during off-peak hours

Best Practices

1. Regular Syncs: Set up regular sync schedules to keep your knowledge base current
2. Content Organization: Organize your Zendesk articles into clear categories and folders for better organization in Brainfish
3. API Token Security: Keep your API tokens secure and rotate them periodically
4. Monitor Usage: Check your Zendesk API usage to ensure you stay within rate limits

Support

If you encounter any issues during setup, please contact our support team with:

• Your Zendesk domain
• The specific error message you're seeing