New Integration: Intercom

Description

Add Intercom integration to sync customer conversations, contacts, companies, and help center articles into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/hubspot/ - Similar CRM/customer platform
• integrations/slack/ - Messaging and conversation sync reference
• integrations/linear/ - Project management integration

Required Files Structure

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

Intercom API Integration

OAuth Setup

• Use OAuth 2.0
• Current API version: 2.15
• Set API version via Intercom-Version HTTP header
• Required scopes: Conversations, Contacts, Companies, Help Center, Data Events
• Base URL: https://api.intercom.io

Key Endpoints

• GET /conversations - List all conversations
• GET /conversations/{id} - Get a specific conversation
• GET /contacts - List/search contacts
• GET /contacts/{id} - Get a specific contact
• GET /companies - List all companies
• GET /articles - List help center articles
• GET /admins - List all admins/teammates
• GET /data_events - List data events for a user
• GET /teams - List all teams
• GET /tags - List all tags

Events to Track

1. Conversations - New conversations, replies, assignments, closures, reopens
2. Contacts - New leads, new users, contact updates
3. Companies - New companies, updates
4. Articles - Published, updated help center articles
5. Notes - Notes added to contacts

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts
• Create API utilities in utils.ts with Intercom API v2.15 client
• Implement sync logic in schedule.ts for conversations, contacts, companies
• Convert Intercom events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• REST API v2.15 is the latest version
• Version must be set via Intercom-Version header on each request
• OpenAPI specification available at github.com/intercom/Intercom-OpenAPI
• Supports webhooks for real-time event notifications
• Pagination uses cursor-based pagination
• Rate limits apply per app
• Intercom provides scroll API for bulk data export

Resources

• Intercom API v2.15 Reference
• Intercom REST API Overview
• Intercom Developers Portal
• API Changelog
• Intercom OpenAPI Spec

Labels

enhancement, integration, new-feature