Skip to main content

​
Overview

The botBrains Zendesk integration enables AI-powered automation for your customer support team. By connecting your Zendesk account, botBrains can automatically respond to tickets, predict ticket fields, and help resolve customer inquiries faster.

​
Key Benefits

  • Automated Ticket Responses: Let botBrains draft or post responses to customer tickets
  • Intelligent Field Prediction: Automatically categorize tickets, set custom fields, and select appropriate ticket forms
  • Private Mode Option: Review AI-generated responses before they’re sent to customers
  • Import Historical Data: Import past tickets to improve AI training
  • Seamless Integration: Automatic webhook and trigger setup in your Zendesk account

​
Prerequisites

Before setting up the Zendesk integration, you’ll need:
  • A Zendesk account with admin access
  • An active botBrains project
  • A Zendesk API token (we’ll show you how to create one)

​
Setting Up Your Zendesk Integration

​
Step 1: Navigate to Channels

  1. Open your botBrains project
  2. Navigate to Channels in the sidebar
  3. Click on the Zendesk integration option

​
Step 2: Add Your Zendesk Account

Click the Add Zendesk Integration button to open the configuration form.

​
Step 3: Configure Integration Settings

​
Integration Name

Choose a descriptive name for this integration (e.g., “Main Support Zendesk”).

​
Zendesk Subdomain

Enter your Zendesk subdomain. If your Zendesk URL is your-company.zendesk.com, enter your-company.

​
Zendesk Agent Email

Provide the email address of an agent in your Zendesk account. botBrains will use this agent profile to post responses. You can:
  • Use an existing agent’s email
  • Create a dedicated agent account for botBrains (recommended)
If your chatbot is named “Alex”, consider creating an agent with email alex@company.com for consistency.

​
Zendesk API Token

You’ll need to create an API token in Zendesk:
  1. Log into your Zendesk Admin Center
  2. Navigate to Apps and integrations > APIs > Zendesk API
  3. Click the Settings tab
  4. Enable Token Access if not already enabled
  5. Click Add API token
  6. Add a description (e.g., “botBrains Integration”)
  7. Click Create
  8. Copy the generated token and paste it into the botBrains form
A video tutorial is available in the integration form. Click “Watch: How to create a Zendesk API Token?” to view a step-by-step guide.
Save your API token securely. Zendesk only shows it once. If you lose it, you’ll need to generate a new token.

​
Private Mode

Enable this option if you want botBrains to draft responses as internal notes instead of public comments. This is useful for:
  • Reviewing AI responses before sending them to customers
  • Testing the integration without affecting customer-facing tickets
  • Having human agents approve all responses
When enabled, botBrains will:
  • Create internal notes instead of public comments
  • Not modify ticket fields automatically
  • Not change ticket status
Private mode is enabled by default when creating a new integration. This ensures safe testing before going live.

​
Read Only Mode

Enable this option to prevent botBrains from making any changes to Zendesk. When enabled:
  • botBrains can read ticket data but cannot write
  • The initial setup script will not run
  • The webhook and trigger will only be created when you disable read-only mode
Read-only mode is enabled by default when creating a new integration. This ensures safe testing and evaluation before giving full access. You must disable read-only mode for the integration to become active and start receiving events.

​
Step 4: Save and Enable

  1. Click Create Integration to save your settings
  2. Your integration will appear in the list with detailed information:
    • Group ID: The Zendesk group associated with the integration
    • Webhook ID: The webhook ID (shown once enabled)
    • Trigger ID: The trigger ID (shown once enabled)
  3. Toggle the Integration Status switch to enable the integration
When you enable the integration, botBrains will automatically:
  • Create a webhook in your Zendesk account
  • Set up a trigger to notify botBrains of new ticket events
  • Associate the integration with a Zendesk group (if configured)
You can click on the Webhook ID or Trigger ID to view them directly in your Zendesk admin panel.

​
Configuring the Field Predictor

The Field Predictor uses AI to automatically select ticket forms, categorize tickets, and fill custom fields based on ticket content.

​
Accessing the Predictor

  1. Find your Zendesk integration on the Channels page
  2. Click the Predictor button on the integration card
  3. You’ll see the predictor configuration page with all available ticket fields

​
Predictor Configuration

​
Enable/Disable the Predictor

At the top of the page, toggle the Active/Disabled switch to enable or disable the entire predictor feature.

​
General Instructions

Provide instructions explaining when to use which ticket form. This helps the AI select the appropriate form based on the ticket content. Example: 
Use the Bug Report form for technical issues and crashes.
Use the General Inquiry form for billing questions.
Use the Feature Request form when customers suggest improvements.

​
Field Filtering

Use the filter badges to view specific sets of fields:
  • All Fields: Shows all available ticket fields
  • Enabled Fields: Shows only fields you’ve enabled for prediction
  • Ticket Form Names: Click on a specific form to see only fields associated with that form
Click on “Manage Forms” to open the Zendesk admin panel and manage your ticket forms.

​
Field Configuration

For each field you want to predict:
  1. Enable the field: Toggle the switch next to the field name to enable prediction
  2. Pre-Completion: Enable this if the field should be predicted before generating the AI response (useful for fields that influence the response)
  3. Prediction Instructions: Provide specific guidance for how this field should be predicted
Example instructions for a Priority field: 
Set priority to "High" for issues affecting multiple users or business-critical functions.
Set to "Medium" for individual user issues.
Set to "Low" for feature requests and general inquiries.
Each field card shows:
  • Field name and type
  • Whether it’s active in Zendesk
  • Available field values or options
  • Links to manage the field in Zendesk
Some field types cannot be predicted, such as assignee, group, lookup, and status fields. These are marked with a warning explaining why they’re not supported.

​
Testing Predictions

To test your predictor configuration:
  1. Enter a ticket ID in the Select Ticket section
  2. Click Load to fetch the ticket and display its comments
  3. Choose a test action:
    • Predict Fields: Test only field predictions (shows which fields would be changed)
    • Predict Fields & Comment: Test the full resolution flow (shows fields and the AI-generated response)
  4. Click the action buttons next to individual comments to test predictions from that specific comment
The test results show:
  • Which ticket form would be selected
  • Old values vs. new predicted values for each field
  • For full resolution tests: the AI-generated comment and all field changes
  • A link to view the trace for debugging
Use the “View JSON” buttons to inspect raw ticket data and field configurations.

​
Validation

Click the Validate button to check your predictor configuration for:
  • Required fields that are missing
  • Conflicting settings
  • Invalid field configurations
  • Warnings about potential issues
The validation results will show errors (must be fixed) and warnings (should be reviewed) to ensure your configuration works correctly.

​
Importing Historical Tickets

The Import feature is behind a feature flag. It may not be available for all accounts.
Import past tickets to improve your AI’s training and responses:
  1. Click the Import button on your integration card (if available)
  2. Configure your import parameters:
    • Search Query (optional): Use Zendesk search syntax to filter tickets (e.g., status:solved created>2024-01-01)
    • From Date (optional): Import only tickets created after this date
    • Until Date (optional): Import only tickets created before this date
  3. Enable Dry Run Mode to test your filters without actually importing data
  4. Click Test Import (dry run) or Start Import (actual import)

​
Monitoring Import Jobs

After starting an import job:
  • You’ll be redirected to the job status page
  • The page shows the job ID, status (pending, running, completed, failed)
  • The page auto-refreshes every 10 seconds while the job is running
  • Results are displayed when the job completes
  • Errors are shown if the job fails
Always run a dry run first to verify your filters are selecting the correct tickets before starting a full import.

​
Operating Modes

In private mode, botBrains creates internal notes instead of public comments. This allows your team to:
  • Review AI-generated responses before sending them to customers
  • Make adjustments as needed
  • Build confidence in the AI before going live
When private mode is enabled:
  • AI responses are posted as internal notes (not visible to customers)
  • Ticket field pre-filling is disabled
  • Ticket status changes are disabled
To use private mode:
  1. Enable Private Mode in your integration settings
  2. botBrains will add internal notes to tickets
  3. Agents can review and send the responses manually

​
Public Mode (Full Automation)

In public mode, botBrains automatically:
  • Posts public responses to tickets (visible to customers)
  • Updates ticket fields based on predictor configuration
  • Changes ticket status (e.g., solving tickets)
Only use public mode after thorough testing in private mode. Ensure your AI is providing accurate responses before enabling public mode.

​
Best Practices

​
Start with Read-Only and Private Mode

Begin with both read-only mode and private mode enabled to safely test the integration without making any changes to your Zendesk account. Once you’re comfortable, disable read-only mode to enable the webhook, then test in private mode before going fully public.

​
Test with Historical Tickets

Use the predictor testing feature with real historical tickets to validate your configuration:
  1. Load a ticket by ID
  2. Test “Predict Fields” to see field changes
  3. Test “Predict Fields & Comment” to see the full resolution
  4. Review the results and refine your instructions

​
Provide Clear Instructions

The more specific your field prediction instructions, the better the AI will perform:
  • Include examples of when to use each option
  • Explain edge cases
  • Reference your internal policies or guidelines
  • Be specific about priority levels, categories, etc.

​
Configure Pre-Completion Fields Strategically

Use pre-completion for fields that influence the AI’s response:
  • Product/service category (helps AI understand context)
  • Customer segment (helps AI adjust tone)
  • Ticket type (helps AI provide appropriate solutions)
Don’t use pre-completion for fields that should be set after reviewing the response:
  • Resolution status
  • Satisfaction ratings
  • Post-resolution categories

​
Monitor Performance

Regularly review the AI’s responses and field predictions:
  • Check internal notes in private mode
  • Review field prediction accuracy
  • Adjust instructions based on patterns you observe
  • Use the validation feature to catch configuration issues

​
Use Ticket Forms Strategically

Configure different ticket forms for different types of inquiries. This helps the AI:
  • Understand the type of issue
  • Select appropriate fields
  • Provide contextually relevant responses

​
Troubleshooting

​
Integration Won’t Enable

If you can’t enable your integration:
  • Verify your API token is correct
  • Ensure the agent email exists in Zendesk
  • Check that your Zendesk account has API access enabled
  • Confirm you have admin permissions in Zendesk
  • Make sure read-only mode is disabled (required for webhook creation)

​
Webhook Not Receiving Events

If botBrains isn’t responding to new tickets:
  1. Check that the integration is enabled (webhook ID should be visible on the integration card)
  2. Verify the webhook exists in your Zendesk admin panel (click the Webhook ID link)
  3. Verify the trigger exists in your Zendesk admin panel (click the Trigger ID link)
  4. Click Rotate Secret to regenerate the webhook credentials if needed
  5. Ensure your Zendesk trigger is active

​
Incorrect Field Predictions

If the AI is setting wrong field values:
  • Review and refine your prediction instructions in the predictor page
  • Add more specific examples to your instructions
  • Test with various ticket types using the testing feature
  • Ensure the field is enabled for the correct ticket forms
  • Check if the field should be set pre-completion or post-completion
  • Use the Validate button to check for configuration issues

​
Fields Not Being Updated

If fields aren’t being updated even with predictor enabled:
  • Check that the predictor is enabled (toggle at top of predictor page)
  • Verify that specific fields are enabled in the field configuration
  • Ensure private mode is disabled (private mode disables field updates)
  • Check that the field is supported (some field types like assignee and group are not supported)

​
Need to Rotate API Token

If you need to update your API token:
  1. Click Edit on your integration card
  2. Enter the new token in the Zendesk API Token field (leave blank to keep current)
  3. Click Save Changes

​
Import Job Fails

If your import job fails:
  • Check the error message on the job status page
  • Verify your search query uses valid Zendesk search syntax
  • Ensure the date range is valid
  • Try a dry run first to test your filters

​
Managing Your Integration

​
Editing Settings

To update your integration:
  1. Hover over your integration card to reveal action buttons
  2. Click the Edit button
  3. Modify the settings as needed (name, subdomain, email, API token, private mode, read-only mode)
  4. Click Save Changes
You can update most settings without disabling the integration. The webhook will continue to work. To update the API token, enter a new token or leave the field blank to keep the current token.

​
Rotating Webhook Secret

If you suspect the webhook secret has been compromised:
  1. Hover over your integration card to reveal action buttons
  2. Click Rotate Secret
  3. The webhook will be updated automatically in Zendesk
The Rotate Secret button is only available when the integration is enabled (webhook ID is present).

​
Accessing Advanced Features

Your integration card shows these action buttons on hover:
  • Edit: Modify integration settings
  • Delete: Remove the integration
  • Predictor: Configure field prediction
  • Import: Import historical tickets (if enabled)

​
Disabling the Integration

To temporarily stop the integration:
  1. Toggle the Integration Status switch off
  2. The webhook and trigger will be deleted from Zendesk
  3. botBrains will stop receiving ticket events
You can re-enable it anytime by toggling the switch back on. This will recreate the webhook and trigger.

​
Deleting the Integration

To permanently remove the integration:
  1. Disable the integration first (toggle off)
  2. Click the Delete button (revealed on hover)
  3. Confirm the deletion
Deleting an integration cannot be undone. All configuration including predictor settings will be lost.

​
Security Considerations

​
API Token Security

  • Store your API token securely
  • Don’t share it with unauthorized users
  • Rotate it periodically or if compromised

​
Agent Account

  • Consider creating a dedicated agent account for botBrains
  • Use a clear name so customers know they’re interacting with AI
  • Set appropriate permissions for the agent

​
Webhook Secret

  • The webhook secret is automatically generated and managed
  • Rotate it if you suspect it’s been compromised
  • Never share it publicly

​
Next Steps

After setting up your Zendesk integration:
  1. Configure the Predictor: Click the Predictor button to set up field prediction rules
  2. Test Thoroughly:
    • Start in read-only and private mode
    • Load historical tickets and test predictions
    • Review internal notes to verify AI responses
    • Use the validation feature to check your configuration
  3. Import Historical Data (if available): Import past tickets to improve AI training
  4. Go Live Gradually:
    • Disable read-only mode to enable the webhook
    • Test in private mode with live tickets
    • Monitor performance and refine instructions
    • Transition to public mode once confident
  5. Monitor and Optimize: Regularly review AI responses and field predictions to continually improve performance
For additional help, contact the botBrains support team.