The Complete Guide to Migrating from Help Scout to Intercom
Planning a Help Scout to Intercom migration? This guide explains object mapping, thread history, attachment workarounds, tags, and common pitfalls.
Moving from Help Scout to Intercom is more than just a platform switch. It’s a shift from a shared mailbox style workflow to a full conversational relationship model. Help Scout is organized around mailboxes, customers, and conversations. Intercom, on the other hand, focuses on contacts, companies, and conversations enriched with automation, tickets, and data attributes.
This guide walks you through each step of the process: from defining your scope to rebuilding workflows and managing historical data. You’ll also find insider tactics that only come from engineers who’ve performed this migration multiple times.
1. Define Your Migration Scope
Before exporting anything, decide what you need to move and what you’ll rebuild. Help Scout’s model is simple but broad. It includes customers, conversations, threads, attachments, tags, ratings, and saved replies. Intercom supports all of those concepts, but some of them translate differently.
Data to migrate
- Customers (including addresses, phones, social profiles)
- Organizations
- Conversations and their threads
- Attachments and tags
- Ratings (CSAT)
- Custom fields and properties
- Docs knowledge base.
Configuration to rebuild
- Mailboxes
- Saved Replies
- Routing Rules
- Folders and Views
- Docs navigation, visibility rules, redirects, SEO settings
Data to archive
- Historical reports and performance metrics
- Automation rules and triggers
- Old workflows that have no Intercom equivalent
- Article revision history and analytics that do not map
Once you’ve mapped these, create a migration sheet that captures every Help Scout object, its Intercom destination, and any field transformations needed.
2. Prepare Intercom for Data Import
Before any data import, configure your Intercom workspace so that migrated records have valid relationships.
- Create data attributes. These act as custom fields for Contacts, Companies, and Conversations. Predefine attributes for every Help Scout property you intend to preserve.
- Configure Teams and Agents. Create teams and assign agents before importing conversations.
- Enable Conversation Ratings if you plan to migrate historical CSAT data.
- Review your tag taxonomy. Standardize naming, since both systems use tags but apply them differently.
- Precreate Collections that will receive migrated content.
- Decide your hierarchy strategy and prepare article attributes.
Once done, your Intercom workspace will be ready to receive imported customers, conversations, and relationships.
3. Migrate Objects
This section covers the detailed object mappings and migration order. The logical flow is:
Properties → Organizations → Customers → Conversations → Threads → Attachments → Tags → Ratings → Knowledge Base
3.1 Properties and Custom Fields
Help Scout properties are flexible fields on customers, conversations, or organizations. In Intercom, these map to Data Attributes.
Define each field’s type (string, number, boolean, or date) before import. For example:
| Help Scout Property | Intercom Equivalent | Notes |
|---|---|---|
| custom_fields.priority | conversation_data_attributes.priority | Create custom field first |
| customer_property.industry | contact_data_attributes.industry | Define field in Intercom Settings → Data attributes |
| organization_property.plan_tier | company_data_attributes.plan_tier | Store company-level fields |
3.2 Organizations → Companies
Help Scout Organizations translate directly to Intercom Companies.
Each Company can be identified by its company_id or name, and linked to Contacts.
| Help Scout Field | Intercom Field | Notes |
|---|---|---|
| id | external_id | Keep stable for idempotent imports |
| name | name | Direct mapping |
| domain | domain | Enables auto-linking for contacts |
| custom fields | company_data_attributes | Define before import |
Once companies are imported, verify they appear once per unique domain and are linked to the right contacts.
3.3 Customers → Contacts
Customers are the core of the migration. Every Help Scout Customer becomes an Intercom Contact.
| Help Scout Field | Intercom Field | Notes |
|---|---|---|
| id | external_id | Use to ensure idempotency |
| first_name / last_name | name | Combine into one |
| Required only if external_id is not provided. Intercom allows creating contacts identified solely by external_id | ||
| phone | phone | Normalize to E.164 format |
| address | location fields | Use Intercom’s location.country, region, city |
| chat_handles / social_profiles | custom attributes | Store as text fields or JSON |
| websites[] | custom attributes | Multiple URLs → semicolon-separated string |
| tags[] | tags[] | One-to-one mapping |
Leads or inactive users can be tagged as “legacy-lead” if they no longer exist in your active database.
3.4 Conversations
Help Scout Conversations correspond to Intercom Conversations. The structure is similar. Each Conversation has metadata, tags, custom fields, and multiple threads.
| Help Scout Field | Intercom Field | Notes |
|---|---|---|
| id | external_id | Critical for reruns |
| subject | title | Use first thread message if empty |
| status (active, closed, pending, spam) | state | Map to Intercom open, closed, or snoozed |
| mailbox_id | team_assignee_id | Map based on team created earlier |
| assignee_id | admin_assignee_id | Link to admin ID |
| created_at | created_at | Timestamps preserved (cannot be backdated) |
| tags[] | tags[] | Direct mapping |
| custom_fields | data_attributes | Pre-create all conversation fields |
3.5 Threads → Conversation Parts
Help Scout Threads represent individual messages, notes, or phone logs inside conversations. In Intercom, these become Conversation Parts.
| Help Scout Thread Type | Intercom Equivalent | Notes |
|---|---|---|
| reply | conversation part (public) | Author = contact or admin |
| note | conversation part (internal note) | Mark as internal |
| phone | conversation part (public or note) | Tag as “phone_call” using source.type |
| chat | conversation part (public) | Include messenger timestamp |
| attachments | uploaded file references | Re-upload and attach to part |
| scheduled thread | external scheduler | Use a background job to post replies at correct time |
Maintain chronological order of messages for readability, and attach timestamps in note headers when Intercom prevents backdating.
3.6 Attachments
Help Scout supports direct file attachments per thread. Intercom’s public API does not offer a general upload endpoint for conversation attachments. The workaround is to:
-
Upload files to an external storage (e.g., S3)
-
Insert their signed URLs into the message body
-
Preserve original filenames and author context
If inline images exist, replace base64-encoded content with hosted links.
3.7 Tags
Tags migrate cleanly. Intercom supports tagging Contacts, Conversations, and Companies.
Steps:
-
Create tag taxonomy in Intercom first.
-
Import all unique Help Scout tags.
-
Attach tags to contacts and conversations in the same batch.
This ensures uniform tag references across objects.
3.8 Ratings
Help Scout offers post-conversation satisfaction ratings that appear as “Great,” “Okay,” or “Not Good.” Intercom also supports conversation ratings, but its built-in conversation_rating object is read-only and cannot be populated through the API.
To preserve historical CSAT data from Help Scout, you can store the scores and comments as custom attributes or internal notes instead.
3.9 Saved Replies
Help Scout’s Saved Replies (canned messages) need to be recreated manually as Intercom Inbox Macros.
Export their text and subject from Help Scout and re-import them manually or through Intercom’s UI.
You can group similar replies by use case and assign them to the corresponding Teams.
3.10 Knowledge Base (Docs → Help Center)
Help Scout’s Docs product is structured around Sites, Collections, and Articles, while Intercom organizes knowledge bases as Help Centers, Collections, and Articles. The hierarchy is similar, but Intercom flattens categories and offers richer presentation and search options.
Docs Sites → Help Centers Each Help Scout Docs site maps directly to one Intercom Help Center. If you manage multiple branded Docs sites in Help Scout, create separate Help Centers in Intercom.
Collections → Collections Help Scout Collections (and any nested Categories under them) correspond to Intercom Collections.
| Help Scout Field | Intercom Field | Notes |
|---|---|---|
| id | external_id | Preserve for idempotent imports |
| name | name | Direct mapping |
| slug | custom attribute legacy_slug | Useful for redirects |
| visibility | Help Center visibility | Choose “Public” or “Internal” based on source |
Articles → Articles Help Scout Articles translate directly to Intercom Articles within each Collection.
| Help Scout Field | Intercom Field | Notes |
|---|---|---|
| id | external_id | Required for reruns and deltas |
| name | title | Direct mapping |
| text (HTML) | body | Clean inline styles and image URLs |
| author_id | author_id | Map to existing admin |
| tags[] | tags[] | One-to-one mapping |
| attachments[] | attachments[] | Re-upload and update references |
| category_id | collection_id | Flatten if needed |
| visibility | published state | Set to published or draft |
| translations[] | language-specific articles | Create per-locale variants |
After migration, verify that each article appears under the correct Collection and that internal links resolve to new Intercom article URLs.
Attachments and Images Help Scout allows attachments and inline images. Intercom stores these as uploaded assets within articles. Re-upload files, then replace any src or href references in your HTML body with the new asset URLs.
4. Rebuild Automations, Workflows, and Views
Once data is imported, replicate Help Scout’s operational logic in Intercom:
-
Routing Rules → Workflows. Recreate auto-assignment and prioritization in Intercom’s Workflow Builder.
-
Mailboxes → Teams. Use Teams to segment customer support groups.
-
Folders and Views. Create saved filters in Intercom Inbox to mirror Help Scout’s folder structure (e.g., “My Pending Tickets”).
-
Saved Replies → Macros. Rebuild frequently used responses.
-
SLAs and Business Hours. Configure time-based rules for response expectations.
-
Recreate Help Center navigation using Collections and article ordering. Use your theme or UI to simulate category depth if needed.
-
Reapply visibility and SEO settings. Replicate public or internal visibility using Intercom’s Help Center and Article settings. Populate meta title and description fields as needed.
-
Implement your redirect map at the edge so old Docs URLs resolve to the new Intercom Articles.
5. Manage Gaps and Historical Data
Not everything will fit neatly into Intercom’s data model. Handle these carefully:
| Help Scout Object | Intercom Equivalent | Approach |
|---|---|---|
| Routing Configuration | Workflows | Recreate manually |
| Inboxes | Teams | Create manually, one per mailbox |
| Saved Replies | Macros | Manual recreation |
| Folders | Views | Manual recreation |
| Legacy Mailbox Rules | Workflow exports | Document for audit |
For anything that cannot be replicated (e.g., API rate limits, old automations), export and archive them as CSV or JSON for reference.
6. Insider Secrets (last verified as of DD/MM/YYY)
This is where the hard-won lessons come in. Things only people who’ve done this migration at scale will tell you.
-
Preserve the external IDs Always carry over Help Scout’s id as Intercom’s external_id. It’s your key to idempotent imports and safe delta runs.
-
Normalize timestamps early Help Scout timestamps are in ISO format. Intercom expects UNIX epoch seconds. Convert and round before pushing data.
-
Clean your HTML bodies Help Scout threads often embed signatures, inline images, or broken formatting. Use an HTML sanitizer to convert base64 images into hosted URLs before sending to Intercom.
-
Batch attachments carefully Uploading attachments sequentially can hit API rate limits. Pre-stage uploads in parallel using a job queue, then inject URLs in messages.
-
Handle private notes first Intercom enforces author context more strictly. Import internal notes before public replies to maintain correct chronological order and agent visibility.
-
Backfill company-contact relationships Don’t rely on Intercom’s automatic domain matching alone. Explicitly attach each contact to its company after both exist.
-
Run a pilot migration Pick 50–100 conversations covering all thread types (email, chat, note, phone). Validate formatting, attachments, and timestamps before scaling.
-
Perform a delta sync before go-live On cutover day, pause Help Scout, re-export recent conversations updated in the last few hours, and rerun the import. This keeps both systems perfectly in sync.
Summary
Migrating from Help Scout to Intercom is a structured, multi-phase process.
Define your scope early. Create Intercom Data Attributes, Companies, and Teams before importing.
Migrate Customers, Conversations, Threads, Tags, Attachments, Ratings and Knowledge Base in that order.
Rebuild your workflows manually and document gaps.
If you’d rather not wrestle with mapping sheets and pagination loops, ClonePartner can handle the full migration for you. Every project gets a dedicated engineer who understands the nuances of both APIs and ensures zero downtime.
