Intercom Integration

Intercom tracks product usage, bookings, and support tickets so the success team has context. The wrapper lives in reformer-platform/services/intercom.js and exposes helper functions for common events.

Environment Variables

INTERCOM_ACCESS_TOKEN=...

The token must be an Intercom personal access token with permission to create events.

Event Tracking Helpers

• trackPortalVisit(userId, portalData) — logs portal navigation (portal_type, page_visited, session_duration).
• trackCalBooking(bookingData) — captures Cal.com bookings (booking_type, duration, status).
• trackSupportTicket(ticketData) — records customer support submissions.
• trackOnboardingEvent(userId, eventType, eventData) — tracks onboarding milestones (step, completion percentage, time spent).
• Each helper calls sendEvent(event) which POSTs to https://api.intercom.io/events.

Usage Patterns

• Automation orchestrator hooks call Intercom helpers after Cal bookings and onboarding steps.
• Support flows (Intercom widget, Crisp integration) trigger trackSupportTicket with priority/status metadata.
• All helpers log warnings if INTERCOM_ACCESS_TOKEN is missing, so monitor logs to ensure events aren’t being skipped.

Monitoring

• Watch for Intercom event tracked: … console logs during onboarding/test runs.
• Errors surface as Intercom … tracking failed messages; resolve by verifying token scopes or payload structure.
• Periodically review Intercom event streams to confirm events arrive with expected metadata.

RAGS Integration

The Intercom integration automatically detects URLs in conversation messages and triggers RAGS (Reformer Analysis & Growth Scoring) analysis.

Status (Nov 13, 2025): The webhook endpoint responds correctly, but Intercom is not currently delivering events. Follow the troubleshooting checklist below before relying on Intercom-triggered RAGS runs.

Setup

1. Configure Webhook in Intercom:

   • Go to https://app.intercom.com/a/apps/_/settings/webhooks
   • Create new webhook:
     • Webhook URL: https://reformer-platform.onrender.com/api/intercom/webhook
     • Webhook name: RAGS Analysis
     • Webhook version: 2.0 (or latest)
   • Subscribe to events:
     • ✅ conversation.user.replied
     • ✅ conversation.admin.replied
   • Save webhook

2. Verify Environment Variable:

   • Ensure INTERCOM_ACCESS_TOKEN is set in Render environment variables

Usage

Important: Intercom does NOT use slash commands like Slack. It automatically detects URLs in messages.

Simply paste a URL in any Intercom conversation:

Check out https://example.com

The system will automatically:

1. Detect the URL in your message
2. Start RAGS analysis in the background
3. Post results back to the conversation when complete

Troubleshooting

No response after sending URL:

1. Check webhook is configured in Intercom dashboard
2. Verify webhook URL matches: https://reformer-platform.onrender.com/api/intercom/webhook
3. Check events subscribed: conversation.user.replied, conversation.admin.replied
4. Verify webhook is enabled/active
5. Check server logs in Render dashboard
6. Confirm the webhook was re-saved after the most recent Intercom policy updates (November 2025). If needed, delete and recreate it.

URL not detected:

• Make sure URL starts with http:// or https://
• Try sending just the URL without extra text
• Check server logs to see what message body was received

Loop Prevention & Filtering

• Admin/bot replies, Slack mirrors, and system URLs now get filtered before analysis to avoid infinite loops between Slack ↔ Intercom.
• Messages are ignored if they only contain previously posted RAGS report links or internal .reformer.la URLs.
• All filter decisions are logged with Intercom RAGS: skipped because … so you can audit server logs when debugging.

MCP Automation

Intercom MCP tools enable end-to-end configuration directly from Cursor (see reformer-platform/mcp-servers/intercom-mcp/):

• list_webhooks — audit current subscriptions.
• create_webhook — provision/re-provision the RAGS webhook with the correct delivery URL and topics.
• update_webhook — adjust delivery URL, toggle activation, or replace topics.
• delete_webhook — retire old or incorrect subscriptions.

Use these commands to keep the webhook aligned with production without leaving Cursor:

# Recreate webhook with default topics
"Create Intercom webhook pointing to https://reformer-platform.onrender.com/api/intercom/webhook"

# Pause a noisy webhook
"Update Intercom webhook <subscription_id> set active false"

Cache Clearing & Anonymous Mode

The dashboard includes a utility function to clear Intercom cache and start fresh conversations without previous history.

Usage

Call clearSession() from the useIntercom hook to:

• Clear all Intercom cookies, localStorage, and sessionStorage
• Clear IndexedDB data
• Remove Intercom DOM elements and scripts
• Boot Intercom in anonymous mode (no user identity)
• Show toast notification for user feedback
• Start a fresh conversation thread

Implementation: dashboard/src/hooks/useIntercom.js

Example:

import { useIntercom } from '../hooks/useIntercom'

function MyComponent() {
  const { clearSession } = useIntercom()
  
  const handleClearCache = () => {
    clearSession() // Shows toast notification automatically
  }
  
  return <button onClick={handleClearCache}>Clear Intercom Cache</button>
}

Anonymous Mode

The useIntercom hook supports anonymous boot mode:

• Checks for intercom_anonymous_mode flag in sessionStorage
• Boots Intercom without user_id, email, or user_hash
• One-time use - flag is cleared after anonymous boot
• Normal boot resumes on next page refresh

When to Use

• Testing support flows as a new visitor
• Starting fresh conversations without previous context
• Debugging Intercom integration issues
• Resetting Intercom state during development

Note: Uses modern toast notification UX instead of dedicated page route for better user experience.

---

Future work: expand to user attributes (plan tier, health score) and bi-directional syncing with CRM.***