The Complete Guide to Migrating from Help Scout to Tidio

Moving customer service platforms is a significant undertaking, but transitioning from Help Scout to Tidio can streamline your support operations.

While Help Scout offers extensive features for managing inboxes and documentation, Tidio focuses on unified communication for live chat, customer contacts, and ticket management.

Successfully making this shift requires careful planning, specifically identifying which assets can be automatically transferred using Tidio's robust API capabilities and which crucial organizational components must be manually rebuilt.

This guide walks you through the process, ensuring your historical data and operational structure land safely in your new environment.

Pre-Migration Checklist

Before you touch any data, run through this checklist:

• Export a full backup of your Help Scout data (Customers, Conversations, Docs) via the Help Scout Mailbox API and Docs API
• Audit your Help Scout custom fields and map each one to a Tidio Contact Property (see field mapping table below)
• Create all Operators in Tidio manually (the API does not support Operator creation)
• Create all Departments in Tidio manually (the API does not support Department creation)
• Define all Contact Property definitions in the Tidio panel before importing data
• Identify conversations with file attachments — these require separate handling (see Attachments section)
• Set up a staging/test Tidio project to validate your migration scripts before running against production
• Confirm your Tidio plan includes API access (check Tidio's pricing page for plan-level API availability)

Define Your Migration Scope

A smooth migration hinges on a clear understanding of what data moves automatically and what requires manual effort. We can divide the required transfers into three categories:

• Migrated via API (Automated Data Transfer):

These are the core data assets that Tidio's API is designed to handle. Help Scout Customers translate directly into Tidio Contacts. Any associated Customer Properties you track will also be migrated.

Crucially, complex historical data, like Help Scout Conversations, can be reconstructed in Tidio as Tickets by creating the ticket first and then sequentially adding each historical message as a reply — preserving the full thread structure.

• Configured Manually (Pre- or Post-Migration Setup):

Essential organizational elements and specialized content must be manually configured in the Tidio panel.

This includes fundamental entities like Help Scout Users (which become Tidio Operators) and Help Scout Teams (which become Tidio Departments).

Specialized content like Saved Replies and Tags requires manual entry, as do your comprehensive Knowledge Base (Articles, Categories, and Collections).

• Archiving Considerations:

All data assets must be addressed either through API migration or manual setup. The information required for operational configurations, such as Inboxes and Workflows, must also be manually replicated in Tidio.

Field-Level Mapping Reference

The table below maps Help Scout entities and fields to their Tidio equivalents:

Help Scout Entity / Field	Tidio Entity / Field	Notes
Customer	Contact	Core record; at least one of email, first name, last name, or phone required
Customer → Email	Contact → email	Primary identifier
Customer → First Name	Contact → first_name
Customer → Last Name	Contact → last_name
Customer → Phone	Contact → phone
Customer Property (custom)	Contact Property (custom)	Property definitions must be created in Tidio panel before import
Conversation	Ticket	Created via POST /ticket, then messages added as replies
Conversation → Subject	Ticket → subject
Conversation → Status	Ticket → status	Map Help Scout statuses (active, pending, closed) to Tidio equivalents
Conversation → Threads	Ticket → messages (replies)	Each thread entry added sequentially via the reply endpoint
Conversation → Assignee	Ticket → assigned operator	Operator must exist in Tidio before assignment
Conversation → Tags	Ticket → tags	Tags must be created manually in Tidio first
User	Operator	Manual creation only — no API endpoint for this
Team	Department	Manual creation only — no API endpoint for this
Saved Reply	Saved Reply (canned response)	Manual recreation required
Docs Article	Knowledge Base Article	Manual recreation required — no Tidio API endpoint
Docs Category	Knowledge Base Category	Manual recreation required
Docs Collection	Knowledge Base Collection	Manual recreation required
Inbox	Project / Channel settings	Manual configuration in Tidio panel
Workflow	Automation rules	Manual recreation in Tidio

Prepare Tidio for Data Import

Before initiating the transfer of thousands of contacts and tickets, you must lay the organizational groundwork in your Tidio project. This foundational setup ensures that all imported tickets can be correctly assigned and categorized immediately.

Start with your staff structure. Help Scout Users must be manually created as Operators in Tidio.

Similarly, your Help Scout Teams should be manually defined as Departments in Tidio.

The API allows you to retrieve existing Operators and Departments, but not to create or update them, making manual creation mandatory before any historical ticket assignment can occur.

Finally, if you utilize custom data fields, take time now to define your Contact Properties within the Tidio panel. These property definitions must exist before you attempt to push any corresponding custom data fields into your new contacts.

Migrate Objects

By following this sequence, you ensure that primary entities exist before dependent entities are created.

1. Customers to Contacts and Contact Properties

Tidio Contacts represent site visitors identified by information like their name, email, or phone number. Help Scout Customers map directly to this model.

You can create contacts individually via Tidio's contact creation endpoint or, for large migrations, use the batch creation endpoint to process up to 100 contacts per request. When creating a contact, you must provide at least an email, first name, last name, or phone number.

Once the contacts exist, you must transfer their associated data. Tidio contacts can have default properties and various custom properties.

After ensuring the property definitions are set up in the Tidio panel, you can update individual contacts or multiple contacts in a single request, populating them with the customer property data extracted from Help Scout.

See the Tidio API reference for exact endpoint paths and payload schemas.

2. Conversations to Tickets

Help Scout Conversations are migrated as Tidio Tickets, which are designed to record complex interactions that often require multiple communications, including emails and internal messages.

The logical sequence to preserve thread history:

First, you create the main record, initiating the ticket in Tidio. This establishes the ticket identity.

Next, you populate the conversation history. Since a ticket often involves numerous messages from operators and customers, you must sequentially add each historical message as a reply to that newly created ticket using the reply-to-ticket endpoint.

This method allows you to reconstruct the entire thread structure within the Tidio system. You can also update ticket parameters like status or assignment using the update ticket endpoint.

3. Attachments and Embedded Content

Help Scout conversations often contain file attachments and inline images. These are not automatically carried over when you recreate message threads as Tidio ticket replies.

You need to:

• Extract attachments from Help Scout conversations via the Help Scout Mailbox API
• Download and store them locally or in cloud storage during migration
• Re-attach or link them when creating the corresponding Tidio ticket replies, if the Tidio API supports attachment upload on the reply endpoint

If Tidio's API does not support direct attachment upload on ticket replies, you may need to host files externally and include download links within the message body. Verify the current attachment support in the Tidio API reference before building your migration scripts.

Error Handling, Rate Limits, and Rollback

Any migration at scale will hit errors. Plan for them.

Rate Limits: Both the Help Scout and Tidio APIs enforce rate limits. Check the Tidio API reference and Help Scout API docs for current limits. Build throttling into your migration scripts — a simple backoff-and-retry loop that respects 429 responses will prevent your migration from stalling.

Error Handling: Log every API request and response during migration. When a batch request fails (remember: Tidio uses all-or-nothing batch processing), you need to identify the offending record, fix it, and retry the full batch. Keep a running log of:

• Successfully migrated record IDs
• Failed batches with the error response
• Records skipped due to validation issues

Rollback Strategy: Tidio does not offer a built-in rollback mechanism, and deletions are irreversible. Your rollback strategy is your backup. Before starting:

• Keep your complete Help Scout export untouched as the source of truth
• Run your full migration against a staging Tidio project first
• Only migrate to production after validating the staging results

If a production migration fails partway through, you can use your migration logs to identify what was already created and resume from the point of failure rather than starting over.

Post Migration Configuration

Once your core transactional data (Contacts and Tickets) has successfully landed, the final stage is rebuilding the specialized, human-centric assets that require manual attention.

• Knowledge Base Content:

Your Help Scout Docs contain valuable information structured as Articles, Categories, and Collections.

The Tidio API does not offer endpoints for managing this content, meaning all Help Scout documentation must be manually transferred and restructured within Tidio's knowledge base feature.

• Saved Replies and Tags:

These efficiency boosters must also be manually rebuilt. Help Scout manages Saved Replies and Tags via its API, but corresponding automated management features are not available in the Tidio API.

Re-entering your saved replies and manually organizing your tagging structure is a necessary post-migration step.

• Inboxes and Workflows:

The channel configuration defined by Help Scout Inboxes must be manually replicated within your Tidio project settings.

Similarly, any automated business processes defined as Workflows in Help Scout must be manually recreated in Tidio to ensure your support logic continues to run seamlessly.

• Email Channel Continuity:

If your Help Scout setup handles email-based support, you will need to update your DNS records (MX, SPF, DKIM) to route incoming support email through Tidio instead. Failing to do this means new customer emails will continue arriving in Help Scout after you have migrated. Coordinate DNS changes with your domain administrator and plan for a brief overlap period where you monitor both platforms.

Post-Migration Validation Checklist

After migration, verify everything landed correctly:

• Spot-check a sample of Contacts — confirm all fields and custom properties are populated correctly
• Verify total Contact count in Tidio matches the expected count from Help Scout
• Open several migrated Tickets and confirm the full message thread is intact and in the correct chronological order
• Confirm Ticket assignments point to the correct Operators
• Verify Tags on migrated Tickets are present and correctly applied
• Test a Saved Reply to confirm it was recreated accurately
• Browse Knowledge Base articles to confirm content and categorization are correct
• Send a test email to your support address and confirm it arrives in Tidio (not Help Scout)
• Confirm no duplicate Contacts were created (especially if you ran partial imports during testing)
• Validate that Workflows / automation rules trigger correctly on new incoming tickets

Operational Notes

Having successfully navigated this specific migration, there are subtle operational nuances that can save you considerable effort.

The batch processing capability for contacts is essential for moving large datasets quickly, but exercise extreme caution. Tidio uses an "all or nothing" strategy for batch creation and updates, meaning if even one contact record within a batch of up to 100 contacts is invalid due to formatting or missing requirements, the entire request fails. Thorough pre-migration data validation is your best friend here. Validate every record against the required schema before including it in a batch.

When you are creating new contacts in Tidio, remember that the creation endpoint does not perform upserts. If you attempt to create a contact that already exists (matching by email or other identifier), it will simply add a new, duplicate contact. The API does not overwrite data based on matching an email or distinct ID during the creation process. Be mindful of data duplication if you run a partial list twice — deduplicate your input data and track which records have already been successfully created.

Finally, while managing large amounts of historical data, always keep in mind the finality of deletion. Whether deleting contacts or tickets, these actions are irreversible. Run your migration against a staging environment and validate before touching production data.

Summary

Migrating from Help Scout to Tidio is a structured process that combines the power of automated data transfer with meticulous manual configuration.

By prioritizing the setup of foundational elements like Operators and Departments first, followed by the API transfer of Contacts and Tickets, you establish a robust and functional environment.

Dedicating sufficient time to manually rebuild your Knowledge Base, Saved Replies, and Workflows ensures that your team maintains efficiency and access to all necessary resources in your new Tidio system.

Further reading:

• Help Scout Mailbox API
• Help Scout Docs API
• Tidio API Reference