Intercom Integration

Intercom Integration #

BonsAI automatically syncs user and organization data to Intercom for customer communication and support. This integration runs through our Clerk webhook handler, ensuring all user and organization changes are reflected in Intercom in real-time.

Overview #

The Intercom integration provides:

  • Automatic User Sync: Users are created/updated in Intercom when they join organizations
  • Organization Sync: Organizations are synced as companies in Intercom
  • Invitation Tracking: Invited users appear in Intercom before they accept invitations
  • User-Company Associations: Users are properly associated with their organizations
  • Deletion Sync: Deleted users and organizations are removed from Intercom

Architecture # 

Clerk Events → BonsAPI Webhook → Intercom API
                    ↓
                Database

Data Flow #

User Creation/Update #

  1. User signs up or updates profile in Clerk
  2. Clerk sends webhook to BonsAPI
  3. BonsAPI updates database
  4. BonsAPI syncs user to Intercom with organization associations

Organization Creation/Update #

  1. Organization created/updated in Clerk
  2. Clerk sends webhook to BonsAPI
  3. BonsAPI updates database
  4. BonsAPI creates/updates company in Intercom

User Invitations #

  1. Admin invites user via BonsAPI
  2. Invitation created in Clerk
  3. BonsAPI creates “invited” contact in Intercom
  4. When user accepts, invited contact is converted to active user

Configuration #

Environment Variables # 

# Required in deployment.yaml
INTERCOM_ACCESS_TOKEN=your_intercom_access_token
ENVIRONMENT_NAME=production  # or development, staging

Deployment #

The Intercom integration is configured in:

  • deployment/resources/bonsapi/deployment.yaml - Environment variables
  • apps/bonsapi/src/model/app/app_config.rs - Configuration struct

Data Mapping #

Organizations → Companies #

BonsAI Field Intercom Field Notes
external_id company_id Clerk organization ID
name name Organization name
created_at custom_attributes.created_at Unix timestamp
- custom_attributes.environment From ENVIRONMENT_NAME

Users → Contacts #

BonsAI Field Intercom Field Notes
external_id external_id Clerk user ID
name name User’s full name
email email User’s email
- custom_attributes.environment From ENVIRONMENT_NAME
- companies Associated organizations

Invited Users #

Invited users have special handling:

  • external_id: invitation_{invitation_id}
  • Tagged with: invited-user
  • No activity timestamps (signed_up_at, last_seen_at)
  • Custom attribute: status: "invited"

Initial Data Sync #

For existing data, use the sync script:

# From the project root
cargo run --bin sync_intercom_data

# With custom environment
ENVIRONMENT_NAME=staging cargo run --bin sync_intercom_data

This script will:

  1. Sync all organizations as companies
  2. Sync all users with their organization associations
  3. Apply rate limiting to avoid API limits

Error Handling #

The integration is designed to be resilient:

  • Non-blocking: Intercom sync failures don’t fail webhook processing
  • Retry Logic: Built-in exponential backoff for transient failures
  • Rate Limiting: Automatic handling of 429 responses
  • Logging: All sync operations are logged for debugging

Monitoring #

Monitor the integration through logs:

# Success logs
"Successfully synced user {} to Intercom"
"Successfully synced organization {} to Intercom"

# Error logs
"Failed to sync user {} to Intercom: {}"
"Failed to sync organization {} to Intercom: {}"

Troubleshooting #

Common Issues #

  1. Missing Environment Variables

    • Ensure INTERCOM_ACCESS_TOKEN is set in Kubernetes secrets
    • Verify ENVIRONMENT_NAME is configured

  2. Rate Limiting

    • The client automatically handles rate limits with retry
    • For bulk operations, use the sync script with built-in delays

  3. Sync Failures

    • Check logs for specific error messages
    • Verify Intercom API token has correct permissions
    • Ensure user/org data is valid (email format, etc.)

Manual Sync #

To manually sync a specific user or organization:

  1. Trigger a Clerk webhook replay
  2. Or use the sync script with filters (modify as needed)

Testing #

Local Testing #

  1. Set up environment variables:
export INTERCOM_ACCESS_TOKEN=your_test_token
export ENVIRONMENT_NAME=development
  1. Create test invitations and verify in Intercom
  2. Accept invitations and verify user conversion
  3. Update users/orgs and verify changes

Verification #

Check Intercom for:

  • Users appear with correct external_id
  • Organizations appear as companies
  • User-company associations are correct
  • Invited users have “invited-user” tag
  • Environment custom attribute is set

Security #

  • API tokens stored in Kubernetes secrets
  • No sensitive data logged
  • HTTPS only communication
  • Read/write access limited to contacts and companies

Limitations #

  • User created_at timestamp not available (AppUser model limitation)
  • Billing plan information not synced (requires billing service integration)
  • No two-way sync (Intercom changes don’t update BonsAI)