New Integration: Gorgias

Description

Add Gorgias integration to sync e-commerce helpdesk tickets, customers, and messages into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/hubspot/ - Similar customer support system
• integrations/slack/ - Messaging integration reference
• integrations/linear/ - Ticket tracking integration

Required Files Structure

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

Gorgias API Integration

OAuth Setup

• Use HTTP Basic Authentication (username + password from API settings)
• Credentials available at: https://{domain}.gorgias.com/app/settings/api
• Base URL: https://{domain}.gorgias.com/api/

Key Endpoints

• GET /api/tickets - List all tickets
• GET /api/tickets/{id} - Get a specific ticket
• GET /api/tickets/{id}/messages - Get ticket messages
• GET /api/customers - List all customers
• GET /api/customers/{id} - Get a specific customer
• GET /api/users - List all support agents
• GET /api/tags - List all tags
• GET /api/events - List events
• POST /api/tickets - Create a ticket

Events to Track

1. Tickets - Created, updated, resolved, closed, reopened
2. Messages - Customer messages, agent replies, internal notes
3. Customers - New customers, customer updates
4. Tags - Tags applied/removed from tickets
5. Assignments - Ticket assignments to agents/teams

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement HTTP Basic Auth flow in account-create.ts
• Create API utilities in utils.ts with Gorgias REST API client
• Implement sync logic in schedule.ts for tickets, customers, messages
• Convert Gorgias events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• RESTful API with JSON responses
• HTTP Basic Authentication using credentials from Settings > REST API
• Supports webhooks (HTTP integrations) for real-time event notifications
• Designed for e-commerce helpdesk use cases (deep Shopify, Magento, BigCommerce integrations)
• Pagination via cursor parameter
• Rate limits apply per account
• Only admin users can access API settings

Resources

• Gorgias REST API Documentation
• Gorgias Developers Portal
• Gorgias Help Center
• Gorgias API Postman Collection
• HTTP Integrations (Webhooks)

Labels

enhancement, integration, new-feature

Read integrations/hubspot/, integrations/slack/, integrations/linear/, and the integrations/github/src/index.ts pattern before designing the new integration. Implement the listed files under integrations/gorgias/ with authentication, API utilities, synchronization, activity conversion, error handling, and documentation, then add it to integrations/README.md.