# 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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "articleLocale": "en-us"
}
```

```json
{
  "articleLocale": "es"
}
```

```json
{
  "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](/getting-started/ask-a-question.md) with support questions
2. [Create support-focused agents](/product/overview/add-an-ai-agent-persona.md)
3. [Monitor which articles AI references most](/product/monitoring/view-analytics.md)
4. Identify gaps in help center coverage
5. Iterate on article content based on AI usage

## Related Connectors

* [Slack](broken://pages/ZqCVeDsUAq2s0edspK89) - Import support channel discussions
* [Confluence](/product/data-integrations/confluence.md) - Internal knowledge base
* [Website](/product/data-integrations/website.md) - Public documentation sites
* [Files](/product/data-integrations/files.md) - 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 https://help.twig.so/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.