The Complete Guide to Migrating from Help Scout to Intercom

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.

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.

1. Create data attributes. These act as custom fields for Contacts, Companies, and Conversations. Predefine attributes for every Help Scout property you intend to preserve.
2. Configure Teams and Agents. Create teams and assign agents before importing conversations.
3. Enable Conversation Ratings if you plan to migrate historical CSAT data.
4. Review your tag taxonomy. Standardize naming, since both systems use tags but apply them differently.
5. Precreate Collections that will receive migrated content.
6. 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
email	email	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 — the individual message entries within a conversation object.

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:

1. Create tag taxonomy in Intercom first.

2. Import all unique Help Scout tags.

3. 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. API Rate Limits

Both platforms enforce rate limits that directly affect migration speed and reliability.

Help Scout API (Mailbox API 2.0)

Limit	Value
Requests per minute	200 per app per user
Pagination	Max 50 items per page
Docs API	Separate rate limits apply

Intercom API (REST API 2.x)

Limit	Value
Requests per minute	Varies by plan; typically 1,000 for most workspaces
Burst limit	Short bursts above baseline may trigger 429 responses
Search queries	20 per minute (contact/company search)
Attachment size	20 MB per file

When you hit a 429 response, back off using the Retry-After header value. Build retry logic with exponential backoff into your migration scripts — a simple retry loop without backoff will just keep hitting the limit.

For large migrations, the Intercom search endpoint (20 requests/min) is often the real bottleneck, not the general API limit. Plan your deduplication and lookup logic around this constraint.

6. 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., old automations), export and archive them as CSV or JSON for reference.

7. Common Failure Modes

These are the things that break silently during a Help Scout to Intercom migration. Know them before you start.

1. Orphaned contacts. If a conversation references a customer that failed to import (bad email, missing external_id), the conversation will either fail or be created without a contact association. Always verify contact import counts before starting conversation imports.

2. Duplicate company creation. Intercom's auto-association by email domain can create duplicate companies if you also explicitly import companies. Disable domain-based auto-creation during the migration, or import companies first and verify before enabling it.

3. Malformed HTML bodies. Help Scout threads frequently contain broken HTML — unclosed tags, inline styles from email clients, and base64-encoded images. These can render incorrectly in Intercom or cause API rejections. Sanitize HTML before import: strip inline styles, close open tags, and convert base64 images to hosted URLs.

4. Broken attachment references. If you upload attachments to S3 and inject signed URLs into message bodies, those URLs will expire. Use long-lived URLs or permanent public links for attachments that need to remain accessible.

5. Timezone and timestamp mismatches. Help Scout returns ISO 8601 timestamps. Intercom expects UNIX epoch seconds. If you don't convert correctly, conversation parts may appear out of order or with wrong dates. Validate timestamp conversion on a sample batch before running the full migration.

8. Post-Migration Validation

A migration without validation is a migration you hope worked. Run these checks before declaring success.

Count verification:

• Total contacts in Help Scout vs. total contacts in Intercom
• Total conversations exported vs. total conversations created
• Total articles per collection in Help Scout vs. Intercom

Relationship verification:

• Sample 20–30 contacts and confirm they are linked to the correct company
• Sample 10–15 conversations and verify the correct contact is associated
• Verify that conversations assigned to specific agents/teams in Help Scout are assigned to the corresponding admins/teams in Intercom

Content verification:

• Open 10 conversations with multiple thread types (reply, note, phone) and confirm all parts appear in correct chronological order
• Check 5 conversations with attachments — confirm URLs resolve and files are downloadable
• Verify that CSAT data stored as custom attributes matches the original Help Scout rating values

Knowledge base verification:

• Confirm every collection exists and contains the expected number of articles
• Spot-check 10 articles for correct formatting, images loading, and internal links resolving
• Test old Docs URLs against your redirect map

If any count is off by more than 1%, investigate before go-live. Common culprits: API pagination errors, contacts rejected for missing email/external_id, or conversations skipped due to malformed thread data.

9. Rollback Strategy

Plan for the possibility that something goes wrong after cutover.

Before go-live:

• Keep Help Scout active and receiving mail until Intercom is fully validated
• Do not delete or archive any Help Scout data until at least 2 weeks after successful cutover
• Export a full backup of Help Scout data (contacts, conversations, articles) as JSON or CSV before starting any imports

If rollback is needed:

• Re-enable Help Scout mailboxes and MX records
• Any conversations that arrived in Intercom during the cutover window will need to be manually triaged or re-imported back
• Intercom does not offer a bulk delete API for conversations — if you need to clean up a failed import, you'll need to work with Intercom support or delete records individually

The safest approach is to run both systems in parallel during cutover: Help Scout stays live while Intercom receives the migration. Only cut MX records and disable Help Scout after validation passes.

10. Migration Tactics

These are hard-won lessons from running this migration at scale.

1. 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.

2. Normalize timestamps early Help Scout timestamps are in ISO format. Intercom expects UNIX epoch seconds. Convert and round before pushing data.

3. 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.

4. 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.

5. Handle private notes first Intercom enforces author context more strictly. Import internal notes before public replies to maintain correct chronological order and agent visibility.

6. Backfill company-contact relationships Don't rely on Intercom's automatic domain matching alone. Explicitly attach each contact to its company after both exist.

7. Run a pilot migration Pick 50–100 conversations covering all thread types (email, chat, note, phone). Validate formatting, attachments, and timestamps before scaling.

8. 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. Validate counts, relationships, and content before cutting over. Keep Help Scout live until you're confident the migration is clean.

Further reading:

• Help Scout API documentation
• Intercom API documentation