New Integration: Gong

Description

Add Gong integration to sync call recordings, transcripts, deal intelligence, and user activity into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/github/ - OAuth-based integration
• integrations/linear/ - For reference
• integrations/slack/ - Similar communication platform patterns

Required Files Structure

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

Gong API Integration

OAuth Setup

• Use OAuth 2.0 (Authorization Code Grant) per RFC 6749
• Base URL: https://api.gong.io/v2/ (varies per customer - use api_base_url_for_customer)
• Authorization URL: https://app.gong.io/oauth2/authorize
• Token URL: https://app.gong.io/oauth2/generate-customer-token
• Required scopes (space-delimited):
  • api:calls:read:basic - Read basic call data
  • api:calls:read:extensive - Read detailed call data including transcripts
  • api:calls:read:media - Access call media/recordings
  • api:users:read - Read user information
  • api:stats:user-actions - Read user action statistics
  • api:meetings:user:create - Create meetings
  • api:crm:read - Read CRM data synced with Gong
  • api:flows:read - Read Engage flow data

Key Endpoints

• POST /v2/calls - List calls (with filters)
• GET /v2/calls/{id} - Get call details
• POST /v2/calls/transcript - Get call transcripts
• POST /v2/calls/extensive - Get extensive call data
• GET /v2/users - List users
• GET /v2/users/{id} - Get user details
• POST /v2/stats/activity/scorecards - Get scorecard stats
• POST /v2/stats/activity/day-by-day - Get daily activity stats
• POST /v2/stats/interaction - Get interaction stats
• POST /v2/data-privacy/erase - GDPR data erasure
• GET /v2/flows - List Engage flows
• POST /v2/flows/prospects - Manage flow prospects

Events to Track

1. Calls & Meetings

   • New calls recorded
   • Call transcripts available
   • Call scores and highlights
   • Meeting scheduling events
   • Speaker talk ratios and engagement metrics

2. User Activity

   • Daily activity summaries
   • Scorecard completions
   • Call coaching interactions
   • Team performance metrics

3. Deals & CRM

   • CRM data sync events
   • Deal stage changes tracked via calls
   • Engagement flow assignments
   • Prospect interactions

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts
• Create Gong API utilities in utils.ts
• Implement sync logic in schedule.ts using calls and stats endpoints
• Convert Gong events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Gong does NOT support user-level OAuth; authentication happens at a global/organization level.
• The api_base_url_for_customer returned during OAuth flow is unique per customer and MUST be used as the base URL for all subsequent API calls.
• Most list/search endpoints use POST (not GET) with JSON request bodies for filtering.
• Gong API access requires explicit approval from Gong - you must request API access through their partner program or customer portal.
• Call transcripts can be very large; implement pagination and chunking.
• Rate limits are enforced but specific limits depend on the customer's plan.
• The Engage API (for flows/sequences) was added in 2025 and is a separate set of endpoints.

Resources

• Gong API Documentation
• Create an OAuth App for Gong
• Receive API Access
• Gong Engage API
• Gong API Reference (Swagger)

Labels

enhancement, integration, new-feature