Intercom Loader
The Intercom loader pulls customer messaging, contact, and conversation data from your Intercom workspace into your data warehouse. It uses Intercom’s REST API with scroll-based pagination and supports incremental sync via the updated_at timestamp.
Prerequisites
- An Intercom workspace (Starter, Pro, or Premium plan)
- An Intercom user with Admin permissions
- A connected Warehouse (target warehouse) with write permissions on the target schema
Authentication
The Intercom loader uses OAuth 2.0 for authentication.
OAuth 2.0 Setup
- In SignalSmith, click Add Loader and select Intercom
- Click Connect with Intercom
- You’ll be redirected to the Intercom authorization page
- Select the workspace you want to connect
- Review the requested permissions and click Authorize
- You’ll be redirected back to SignalSmith with the connection established
SignalSmith requests the following permissions:
| Permission | Purpose |
|---|---|
| Read users and companies | Extract contact and company records |
| Read conversations | Extract conversation and message data |
| Read admins | Extract admin/agent user records |
| Read tags and segments | Extract tag and segment definitions |
SignalSmith automatically handles token refresh. If the OAuth app is uninstalled from your Intercom workspace, you’ll need to re-authenticate.
Available Objects
| Object | API Name | Description | Default Sync Mode |
|---|---|---|---|
| Contacts | contacts | Users and leads in your Intercom workspace (unified contact model) | Incremental |
| Companies | companies | Organizations that contacts belong to | Incremental |
| Conversations | conversations | Support conversations including state, assignee, and tags | Incremental |
| Conversation Parts | conversation_parts | Individual messages, notes, and actions within conversations | Incremental |
| Admins | admins | Intercom team members (agents, admins) | Full Refresh |
| Tags | tags | Tag definitions applied to contacts, companies, and conversations | Full Refresh |
| Segments | segments | User and company segment definitions | Full Refresh |
| Teams | teams | Team definitions for conversation routing | Full Refresh |
| Data Attributes | data_attributes | Custom attribute definitions for contacts and companies | Full Refresh |
| Articles | articles | Help center article content and metadata | Incremental |
Contact Model
Intercom uses a unified contact model where both “Users” (identified contacts) and “Leads” (anonymous or pre-identified contacts) are stored as contacts. The role field distinguishes between user and lead. Custom attributes defined in your Intercom workspace are extracted as additional columns.
Conversation Parts
Conversation parts represent the individual messages, notes, assignment changes, and state transitions within a conversation. They are extracted as a separate table with a foreign key to the parent conversation. This provides the full conversation thread for analysis.
Configuration
| Setting | Description | Default |
|---|---|---|
| Objects | List of objects to sync | — (you choose during setup) |
| Sync Mode | Full Refresh or Incremental (per object) | Incremental |
| Cursor Field | Field used for incremental sync | updated_at |
| Primary Key | Field(s) that uniquely identify a record | id |
| Target Schema | Warehouse schema for Intercom tables | — (required) |
| Table Prefix | Optional prefix for table names | intercom_ |
| Schedule | Sync frequency | Hourly |
Scheduling Notes
- Rate limits: Intercom enforces rate limits based on your plan. Starter plans allow 500 requests per minute; Pro and Premium plans allow higher limits. SignalSmith handles rate limiting with automatic backoff.
- Scroll API: For large contact and company datasets, SignalSmith uses Intercom’s Scroll API, which provides efficient bulk data extraction without consuming standard rate limit quota.
- Conversation parts volume: Conversation parts can be high-volume in active support workspaces. Consider syncing conversations without parts if you only need conversation-level metadata.
- Contact deduplication: Intercom may have duplicate contacts (especially leads). The loader deduplicates by
idin the warehouse, but the source data may still reflect duplicates in Intercom. - Archived contacts: By default, the loader does not include archived contacts. Enable “Include Archived” if you need historical contact data for analysis.
Schema Mapping
Intercom field types are mapped to warehouse-compatible types:
| Intercom Type | Warehouse Type | Notes |
|---|---|---|
string | VARCHAR | |
integer | BIGINT | |
float | DOUBLE | |
boolean | BOOLEAN | |
date | TIMESTAMP | Unix epoch converted to UTC timestamp |
object | JSON / VARCHAR | Nested structures like location, social_profiles |
list | JSON / VARCHAR | Arrays like tags, segments |
Troubleshooting
| Issue | Solution |
|---|---|
| ”401 Unauthorized” | Re-authenticate by clicking “Reconnect” on the loader detail page |
| ”403 Forbidden” on conversations | Ensure the OAuth app has “Read conversations” permission |
| ”429 Rate limit exceeded” | SignalSmith handles rate limits automatically. Reduce sync frequency if persistent |
| Missing custom attributes | Custom attributes must be defined in Intercom before they appear in the schema. New attributes are picked up on the next schema discovery |
| Contacts showing as “lead” | Intercom’s unified contact model includes both users and leads. Filter by role = 'user' in your models if needed |
| Conversation parts table is very large | Consider syncing only conversations (without parts) or reducing the lookback window |
| OAuth app revoked | Re-authenticate from the loader settings page |
Next Steps
- Create a model to transform your raw Intercom data
- Combine messaging data with CRM data for a unified customer view
- Build audiences based on conversation activity