New Integration: Freshdesk

Description

Add Freshdesk integration to sync customer support tickets, contacts, and conversations into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/hubspot/ - Similar CRM/support system
• integrations/linear/ - Project management integration with ticket tracking
• integrations/slack/ - Messaging and conversation sync reference

Required Files Structure

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

Freshdesk API Integration

OAuth Setup

• Use API Key authentication (Freshdesk uses API key-based auth via HTTP Basic Auth with API key as username and "X" as password)
• Base URL format: https://{domain}.freshdesk.com/api/v2/
• Rate limit: Varies by plan (e.g., Blossom: 200/min, Garden: 400/min, Estate: 700/min, Forest: 1000/min)

Key Endpoints

• GET /api/v2/tickets - List all tickets
• GET /api/v2/tickets/{id} - Get a specific ticket
• GET /api/v2/tickets/{id}/conversations - Get ticket conversations
• GET /api/v2/contacts - List all contacts
• GET /api/v2/contacts/{id} - Get a specific contact
• GET /api/v2/agents - List all agents
• GET /api/v2/groups - List all groups
• GET /api/v2/companies - List all companies
• GET /api/v2/products - List all products

Events to Track

1. Tickets - Created, updated, resolved, closed, reopened
2. Conversations - Replies, notes, forwards added to tickets
3. Contacts - New contacts created, contact updates
4. Agents - Agent assignments, status changes

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement API key authentication flow in account-create.ts
• Create API utilities in utils.ts with Freshdesk v2 API client
• Implement sync logic in schedule.ts for tickets, contacts, conversations
• Convert Freshdesk events to CORE activity format
• Add error handling and rate limiting (respect plan-specific limits)
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Freshdesk API v2 uses REST with JSON responses
• Supports CORS for cross-origin requests
• Pagination via page and per_page query parameters (max 100 per page)
• Supports filtering tickets by various fields (status, priority, created_at, updated_at)
• Use updated_since parameter for incremental sync
• Authentication: Base64 encode {api_key}:X for Basic Auth header

Resources

• Freshdesk API v2 Documentation
• Freshdesk Developers Portal
• Freshdesk Data API

Labels

enhancement, integration, new-feature