Zendesk

Import Zendesk Guide articles and support tickets.

Overview

Property	Value
Type	Dynamic (API integration)
Sync Schedule	Daily, Weekly, Manual
Plan	Pro, Enterprise
Authentication	API token + admin email
Content	Help Center articles, tickets (optional)
Article Limit	10,000 per data source
Ticket Lookback	Max 365 days

Use Cases

• Support deflection: Answer questions from Help Center before ticket creation
• Agent assist: Quick lookup of articles during support conversations
• Knowledge migration: Import existing Zendesk content to Twig
• Ticket analysis: Learn from solved tickets (opt-in)

What Gets Imported

Help Center Articles

• Article title and body content
• Article categories and sections
• Article labels and metadata
• Published articles only

Support Tickets (Optional)

• Ticket subject and description
• Ticket comments and responses
• Ticket tags and custom fields
• Resolution notes

Prerequisites

Before setting up the connector, ensure you have:

• Zendesk Support account (Professional or Enterprise plan)
• Admin access to Zendesk
• API access enabled in Zendesk
• Knowledge base with published articles

How to Set Up Zendesk Connector

Step 1: Gather Zendesk Information

You'll need:

1. Zendesk Subdomain - Your Zendesk URL prefix
2. Admin Email - Your Zendesk admin email address
3. API Token - Generated in Zendesk settings

Step 2: Generate Zendesk API Token

1. Log in to your Zendesk account as an admin
2. Click the Admin icon (gear) in the left sidebar
3. Navigate to Apps and integrations → APIs → Zendesk API
4. Click the Settings tab
5. Ensure Token Access is enabled
6. Click Add API Token under "Active API Tokens"
7. Enter a description: "Twig AI Integration"
8. Click Create
9. Copy the token immediately (it won't be shown again)
10. Click Save

Step 3: Find Your Zendesk Subdomain

Your Zendesk subdomain is the prefix in your Zendesk URL:

https://yourcompany.zendesk.com
         ^^^^^^^^^
         This is your subdomain

Example:

• URL: https://acme-corp.zendesk.com
• Subdomain: acme-corp

Step 4: Configure in Twig AI

1. Log in to your Twig AI account
2. Click Data in the main navigation menu
3. Click Add Data Source or the + button
4. Choose Zendesk from the list of connectors

Step 5: Enter Connection Details

Fill in the following fields:

• Name (required): Descriptive name for this connection
  • Example: "Zendesk Help Center", "Support Knowledge Base"
• Description (optional): Additional context
  • Example: "Customer support articles and FAQs"
• Zendesk Subdomain (required): Your subdomain (without .zendesk.com)
  • Example: acme-corp
• Admin Email (required): Your Zendesk admin email
  • Example: admin@acme-corp.com
• API Token (required): The API token you generated
  • Example: A1b2C3d4E5f6G7h8I9j0...

Step 6: Configure Parameters (JSON)

Optional advanced configuration:

{
  "importArticles": true,
  "importTickets": false,
  "ticketStatus": ["solved", "closed"],
  "articleLocale": "en-us",
  "lookBackDays": 365
}

Available Parameters:

Parameter	Type	Description	Default
importArticles	Boolean	Import help center articles	true
importTickets	Boolean	Import support tickets	false
ticketStatus	Array	Ticket statuses to import	["solved"]
articleLocale	String	Article language locale	"en-us"
lookBackDays	Number	Days of history to import	365
categories	Array	Specific category IDs to import	All
sections	Array	Specific section IDs to import	All

Step 7: Test Connection

1. Click Test Config or Test Connection
2. Twig will verify:
   • Subdomain is valid
   • API credentials are correct
   • API permissions are sufficient
   • Help center is accessible
3. Wait for "Connection Successful" message

Step 8: Set Refresh Schedule

Choose how often to sync:

• Never - Manual sync only
• Daily - Sync new/updated content daily
• Weekly - Sync weekly (recommended for most)
• Monthly - Sync monthly (for stable content)

Step 9: Add Tags (Optional)

Add organizational tags:

• Examples: "zendesk", "support", "help-center", "customer-facing"

Step 10: Save and Sync

1. Click Save or Create
2. Initial sync begins automatically
3. Monitor progress in the data sources list
4. Check process logs for any errors

Configuration Examples

Example 1: Help Center Only

Name: Zendesk Help Center
Description: Customer-facing support articles
Subdomain: acme-corp
Email: admin@acme-corp.com
API Token: [your-token]
Parameters:
{
  "importArticles": true,
  "importTickets": false,
  "articleLocale": "en-us"
}
Refresh: Weekly
Tags: zendesk, help-center, support

Example 2: Help Center + Recent Tickets

Name: Zendesk Support Knowledge
Description: Articles and solved support tickets
Subdomain: acme-corp
Email: admin@acme-corp.com
API Token: [your-token]
Parameters:
{
  "importArticles": true,
  "importTickets": true,
  "ticketStatus": ["solved", "closed"],
  "lookBackDays": 90
}
Refresh: Daily
Tags: zendesk, support, tickets

Example 3: Specific Categories

Name: Zendesk Technical Docs
Description: Technical documentation articles only
Subdomain: acme-corp
Email: admin@acme-corp.com
API Token: [your-token]
Parameters:
{
  "importArticles": true,
  "categories": [123456, 789012],
  "articleLocale": "en-us"
}
Refresh: Weekly
Tags: zendesk, technical, docs

Best Practices

1. Start with Help Center Only

Begin by importing only published articles:

{
  "importArticles": true,
  "importTickets": false
}

Add tickets later if needed after validating article imports.

2. Use Appropriate Refresh Frequency

• Daily: If you publish new articles frequently
• Weekly: For moderately active help centers (recommended)
• Monthly: For stable, infrequently updated content

3. Filter by Category

Import only relevant categories:

{
  "categories": [123456, 789012, 345678]
}

To find category IDs:

1. Go to your Zendesk Guide admin
2. Click on a category
3. Look at the URL: https://yourcompany.zendesk.com/hc/admin/categories/123456

4. Limit Ticket Import

If importing tickets:

{
  "importTickets": true,
  "ticketStatus": ["solved"],
  "lookBackDays": 90
}

Caution: Large ticket volumes can impact processing time and storage.

5. Multi-Language Support

For multi-language help centers, create separate data sources:

{
  "articleLocale": "en-us"
}

{
  "articleLocale": "es"
}

{
  "articleLocale": "fr"
}

Understanding Sync Behavior

Initial Sync

• Imports all published articles
• Imports tickets based on lookBackDays
• May take several minutes for large knowledge bases

Incremental Syncs

• Imports only new/updated articles since last sync
• Imports new tickets matching criteria
• Faster than initial sync

What Gets Updated

• Article content changes
• Article title/metadata updates
• New articles published
• New tickets solved/closed

What Doesn't Get Synced

• Deleted articles (remain in Twig until manually removed)
• Unpublished articles
• Draft articles
• Archived tickets (unless specifically configured)

Security & Permissions

Required Zendesk Permissions

The API token must have access to:

• Read articles in Guide
• Read categories and sections
• Read tickets (if importing tickets)
• Read users (for ticket author information)

Recommended: Service Account

Create a dedicated Zendesk admin account:

• Email: twig-integration@yourcompany.com
• Role: Admin (for full API access)
• Purpose: Twig AI Integration only

Benefits:

• Easy to track API usage
• Can be disabled without affecting other integrations
• Clear audit trail

API Token Security

• Store tokens securely (Twig encrypts them automatically)
• Rotate tokens periodically (every 6-12 months)
• Use descriptive token names
• Revoke unused tokens
• Monitor API usage in Zendesk

Monitoring & Maintenance

Check Sync Status

Regularly verify:

• Last sync completed successfully
• Record count matches expectations
• No errors in process logs
• New articles appearing in AI responses

Common Metrics

• Articles Synced: Total help center articles
• Tickets Synced: Total support tickets (if enabled)
• Last Sync Date: When was the last successful sync
• Sync Duration: Time taken for last sync
• Error Count: Number of failed imports

Troubleshooting

Connection Failed

Problem: Test connection fails

Solutions:

• Verify subdomain is correct (without .zendesk.com)
• Check API token is copied correctly
• Ensure email matches a Zendesk admin account
• Verify API access is enabled in Zendesk
• Check API token hasn't expired or been revoked

No Articles Imported

Problem: Sync completes but no articles appear

Solutions:

• Verify help center has published articles
• Check articleLocale matches your content
• Ensure categories aren't restricted by parameters
• Look for errors in process logs
• Verify API permissions include Guide access

Partial Sync

Problem: Some articles missing

Solutions:

• Check if missing articles are published
• Verify locale matches article language
• Review category/section filters
• Check for articles with special characters
• Review Zendesk API rate limits

Sync Taking Too Long

Problem: Sync runs for extended period

Solutions:

• Reduce lookBackDays for ticket imports
• Disable ticket import if not needed
• Filter by specific categories
• Check Zendesk API response times
• Consider splitting into multiple data sources

Outdated Content

Problem: Updates in Zendesk not appearing

Solutions:

• Check last sync date
• Verify refresh frequency is appropriate
• Manually trigger refresh if needed
• Review process logs for sync failures
• Check API token is still valid

Advanced Configuration

Filtering by Labels

While not directly supported via parameters, you can:

1. Create separate categories in Zendesk for different topics
2. Import specific categories via parameters
3. Use tags in Twig to organize content

Excluding Specific Content

To exclude certain articles:

1. Unpublish them in Zendesk (they won't sync), or
2. Move them to a separate category
3. Don't include that category in import parameters

Multi-Brand Support

If you have multiple Zendesk brands:

1. Create separate data sources for each brand
2. Use different API tokens if needed
3. Name sources clearly: "Zendesk Brand A", "Zendesk Brand B"

Ticket Privacy

Important: Be cautious when importing tickets:

• Tickets may contain sensitive customer information
• Personal data (PII) should be handled carefully
• Consider data retention policies
• Review privacy compliance requirements

Recommendations:

• Import only solved/closed tickets
• Use short lookback periods
• Filter by specific ticket tags
• Create agents with restricted access to ticket data

Integration with AI Agents

Creating Zendesk-Specific Agents

1. Create an AI agent for customer support
2. Restrict data sources to Zendesk content
3. Configure tone for customer-facing responses
4. Add sample prompts from common questions

Deflecting Support Tickets

Use Zendesk content to:

• Answer common questions before ticket creation
• Suggest relevant articles in ticket forms
• Provide instant answers in chat widgets
• Reduce support volume

Agent Assistance

Help support agents by:

• Providing instant article lookup
• Suggesting responses from solved tickets
• Finding relevant documentation quickly
• Improving response consistency

Next Steps

After connecting Zendesk:

1. Test the knowledge with support questions
2. Create support-focused agents
3. Monitor which articles AI references most
4. Identify gaps in help center coverage
5. Iterate on article content based on AI usage

Related Connectors

• Slack - Import support channel discussions
• Confluence - Internal knowledge base
• Website - Public documentation sites
• Files - Supplementary support documents

Support

For Zendesk-specific issues:

• Check Zendesk API documentation: https://developer.zendesk.com/api-reference/
• Review Zendesk API status: https://status.zendesk.com/
• Contact Zendesk support for API access issues

For Twig integration issues:

• Review process logs in Twig
• Contact Twig support with error details
• Share specific article or ticket IDs that failed to import

---

Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the ask query parameter:

GET /dev/product/data-integrations/zendesk.md?ask=<question>

The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.