Intercom Integration Overview

The MyNATCA Platform includes a comprehensive Intercom integration for syncing member data and managing customer support contacts. This integration ensures that support teams have immediate access to accurate member information when responding to inquiries.

Features

Automated Daily Sync

Syncs all Active and Retired members from Supabase to Intercom
Runs daily at 2:30 AM UTC via DigitalOcean App Platform cron job
Updates member attributes, positions, and contact information
Automatically resolves duplicate contacts

Lead Conversion & Enrichment

Converts Intercom leads to users when matched to member database
Enriches contacts with member data (region, facility, positions)
Validates and cleans up invalid UUID external_ids
Merges duplicate contacts automatically

Real-time Webhook Integration

Auto-enriches contacts when they message Intercom support
Looks up member data by email in real-time
Updates contact with member number and attributes immediately
Provides email lookup endpoint for manual queries

Tag-Based Manual Re-Sync

Support team can manually trigger member enrichment by tagging conversations
Tag conversation with "mynatca-sync" to re-sync contact data
Automatically reads member number from conversation data attributes
Handles all contact scenarios (LEAD, USER, duplicates)
Auto-removes tag after successful enrichment

Data Quality Management

Archives contacts with no open conversations and no member match
Removes invalid UUID external_ids from old WordPress integration
Handles duplicate contacts by keeping newest, archiving older ones
Validates member matches using multiple data points

Key Components

Component	Purpose	Location
Daily Sync	Automated daily synchronization of Active/Retired members	`/sync/intercom/daily-sync.js`
Audit Script	One-time enrichment and cleanup of existing contacts	`/sync/intercom/audit.js`
Manual Update	Manual contact updates for edge cases	`/sync/intercom/manual-update.js`
Intercom Client	API client with rate limiting and pagination	`/sync/intercom/lib/client.js`
Webhook Handler	Real-time contact enrichment on messages and tag-based re-sync	`/routes/intercom.js`
Phone Formatter	E.164 phone number formatting	`/lib/phoneFormatter.js`
Member Type Helper	Maps member status to Intercom types	`/lib/memberTypeHelper.js`

Data Flow

┌─────────────┐     Daily Sync     ┌──────────┐
│  Supabase   │ ──────────────────▶│ Intercom │
│  (Members)  │    2:30 AM UTC     │          │
└─────────────┘                     └──────────┘
                                          ▲
                                          │
                                          │ Webhook
                                          │
                                    ┌─────┴─────┐
                                    │ Platform  │
                                    │  Server   │
                                    └───────────┘

Environment Variables

The following environment variables are required for Intercom integration:

# Intercom API
INTERCOM_ACCESS_TOKEN=your_intercom_access_token
 
# Supabase (for member data)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_supabase_anon_key
 
# MySQL (for webhook fallback and audit script)
MYSQL_HOST=your_mysql_host
MYSQL_USER=your_mysql_user
MYSQL_PASS=your_mysql_password
MYSQL_DB=your_mysql_database

Quick Start

Run Daily Sync Manually

npm run sync:intercom

Run Audit Script (One-time Setup)

# Preview changes (dry run)
node sync/intercom/audit.js --dry-run --limit=10
 
# Process all contacts
node sync/intercom/audit.js
 
# Process only leads
node sync/intercom/audit.js --leads-only

Manual Contact Update

# Create mappings file
echo '[
  { "contact_id": "67eb0a6e8f72a828ba21c342", "member_number": "12345" }
]' > mappings.json
 
# Update contacts
node sync/intercom/manual-update.js mappings.json