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

Start by comparing integrations/hubspot/, integrations/linear/, integrations/slack/, and integrations/github/src/index.ts. Review the required Freshdesk files and API endpoints, then determine how tickets, contacts, conversations, and events map to CORE activities. Done means the integration structure, authentication, incremental sync, pagination, rate limiting, documentation, and integrations/README.md entry are complete.