New Integration: Zendesk

Description

Add Zendesk integration to sync support tickets, users, organizations, and customer interactions into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/hubspot/ - Similar CRM/customer management system
• integrations/linear/ - For issue tracking patterns
• integrations/github/ - For OAuth and webhooks reference

Required Files Structure

integrations/zendesk/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Zendesk API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Zendesk API Integration

OAuth Setup

• Use OAuth 2.0 Authorization Code flow
• Authorization URL: https://{subdomain}.zendesk.com/oauth/authorizations/new
• Token URL: https://{subdomain}.zendesk.com/oauth/tokens
• Required scopes:
  • read - Access to GET endpoints, includes sideloading related resources
  • write - Access to POST, PUT, DELETE endpoints for creating, updating, deleting resources
  • impersonate - (optional) Allows admin to make requests on behalf of end users
• OAuth clients are registered in Admin Center > Apps and integrations > APIs > OAuth clients

Key Endpoints

Base URL: https://{subdomain}.zendesk.com/api/v2

Tickets

• GET /tickets - List all tickets
• GET /tickets/{id} - Get a specific ticket
• POST /tickets - Create a ticket
• PUT /tickets/{id} - Update a ticket
• DELETE /tickets/{id} - Delete a ticket
• GET /tickets/{id}/comments - List ticket comments
• GET /tickets/{id}/audits - List ticket audits (change history)
• GET /tickets/{id}/tags - List ticket tags

Users

• GET /users - List users
• GET /users/{id} - Get a user
• GET /users/me - Get authenticated user
• GET /users/search?query={query} - Search users

Organizations

• GET /organizations - List organizations
• GET /organizations/{id} - Get an organization
• GET /organizations/{id}/tickets - List tickets for an organization

Search

• GET /search?query={query} - Unified search across tickets, users, and organizations

Webhooks

• POST /webhooks - Create a webhook
• GET /webhooks - List webhooks
• PUT /webhooks/{id} - Update a webhook
• DELETE /webhooks/{id} - Delete a webhook

Other

• GET /ticket_fields - List ticket fields
• GET /ticket_forms - List ticket forms
• GET /groups - List agent groups
• GET /satisfaction_ratings - List satisfaction ratings
• GET /tags - List tags

Events to Track

1. Tickets

   • Ticket created
   • Ticket updated (status change, priority change, assignee change)
   • Ticket solved / closed
   • Ticket comment added (public and internal notes)
   • Ticket rated (satisfaction survey)

2. Users & Organizations

   • New user created
   • User updated
   • Organization created / updated

3. Agent Activity

   • Ticket assigned to agent
   • Agent group changes
   • Ticket escalation

4. SLA & Metrics

   • SLA breach events
   • First response time
   • Resolution time

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 Authorization Code flow in account-create.ts (handle subdomain-based URLs)
• Create Zendesk API utilities in utils.ts (handle cursor-based and offset pagination)
• Implement sync logic in schedule.ts for tickets, users, and organizations
• Convert Zendesk events to CORE activity format
• Add webhook support for real-time ticket and user events
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Zendesk API uses subdomain-based URLs: https://{subdomain}.zendesk.com/api/v2
• Account subdomain must be captured during OAuth setup for all subsequent API calls
• Pagination: cursor-based (preferred) or offset-based; max 100 results per page
• Search API returns max 1,000 results per query, 100 per page
• Rate limits vary by plan: Essential (10 RPM), Team (200 RPM), Professional (400 RPM), Enterprise (700 RPM)
• Use incremental export APIs for bulk syncing: GET /incremental/tickets?start_time={unix_timestamp}
• Sideloading related resources with include parameter reduces API calls
• Ticket audits provide full change history for each ticket
• Bearer token authentication: Authorization: Bearer {access_token}

Resources

• Zendesk API Reference
• Ticketing API Introduction
• OAuth Authentication Guide
• Creating OAuth Tokens
• Webhooks API
• Search API
• Security and Authentication

Labels

enhancement, good first issue, integration, new-feature, new-integration