So you’ve decided to migrate from another application to Intercom and you want to keep your historical data. Now what?
General process overview
Step descriptions
Planning - define the approach you will take: who will be responsible for the migration, whether or not conversations vs. tickets will be created in Intercom, how you will create contacts in Intercom, etc.
Intercom Setup - at least the basics (attributes) should be configured in Intercom in order to complete the mapping exercise.
Mapping - an exercise to define how entities and attributes that exist in your current application configuration will map to entities and attributes in your new Intercom setup.
Export / Import Scripting (the most technical version of this step) - create the process and scripts to either pick up and convert your Zendesk export to JSON or call Zendesk APIs to retrieve contact and ticket data and to call the Intercom APIs to create conversations / tickets.
Batch Testing (UAT: User Acceptance Testing) - once you’ve completed v1 of the scripting, run a batch test on a subset of tickets in order to make updates and iterate on the scripts.
Initial Run - when the scripts are finalized, you’ll set the “Delta Date” as a fixed point in time to collect only the Closed tickets up to that date / time. These Closed tickets can now be migrated to your launch-ready but non-live Intercom Production environment.
Cutover & Deltas - When you’re ready to cutover from Zendesk, which would include forwarding your Support emails into Intercom and / or launching the Intercom Messenger for live chat, now we can migrate the remaining tickets that have been closed since the Delta date / time plus any Open / Pending tickets.
Would you like Intercom's Professional Services team to do this on your behalf?
Click here to chat with the team 💬
Planning
The first question to ask yourself is “why do I need this data?” The answer will impact the structure and style of your migration.
If you need the data for regulatory compliance only, you might consider whether you want this data in a database you can query vs. in Intercom.
If you only need the data in Intercom so that your new Intercom reporting is inclusive of historical data, it’s recommended that you migrate the data in its simplest form (staying away from message by message migration). The key process here is making sure that the attribute values post-migration are complementary to your new processes so that reporting is consistent.
If you need the data to provide the context of a user’s historical interactions in order to resolve their issues today, you can still migrate the tickets in their simplest form, but this would provide the most justification if you do need the message by message migration. Keep in mind that this will inflate the overall number of API calls to Intercom by 10-100x.
If it’s any combination of the above reasons, it’s recommended to migrate into Intercom!
Mapping
Now that you’ve confirmed why you are migrating your data, the next step is to ask yourself “What data needs to be migrated from my source system and in what format?”
Keep in mind:
Every ticket or conversation needs to be associated with an existing user or lead (there is a contact record for every identifiable end-user).
Will these contacts be created as part of the migration or imported beforehand?
These contacts need at minimum a user_id (from your product) or email address.
Will each source ticket / chat / etc. be migrated as an Intercom Conversation or an Intercom Ticket?
Just because something was a ticket in Zendesk, does not mean it has to be a ticket in Intercom. We have temporal conversations that can be either chat or email, customer-facing tickets, and back office tickets - ALL of which have methods to communicate with customers on.
Try to limit the number of different structures you’re creating as it just adds complexity.
Identify which attributes you will migrate and what they should be mapped to Intercom (tickets & contacts).
Identify and plan for any potential edge-cases.
By the end of this phase you have a table or diagram detailing everything you want to migrate and what its Intercom equivalent will be!
Scripting
Now it is time to review the plan with your Implementation Engineer (IE).
This is a chance for both sides to go over the plan and ask any clarification questions prior to creating the scripts.
Your script will change based on whether you are pre-importing the associated contact or if you are creating the contact (user or lead) as part of the process.
The general framework for the creation of a conversation or ticket is:
Retrieve the ticket details from Zendesk.
Either search and match the requester to the Intercom user or create the user record and update its attributes.
Create the conversation / ticket by identifying the channel.
You are creating the conversation by simulating an inbound message from the customer (important for visibility in the Messenger).
Update the conversation / ticket attributes, attachments, & assignment (team & teammate)
Reply to the conversation with an outbound message back to the customer or by adding a note
Use this reply to post the FULL transcript of the conversation (body) from Zendesk rather than the message by message approach.
If you are replying to the customer and created an email channel conversation, these notifications will go out to the customer unless you are not live in the workspace or you are suppressing all email notifications (we can help you with this).
Manage the conversation / ticket state
All closed tickets will first go through the process of being opened, updated, and replied to before they are closed by this call. It’s important here to make sure all workflows that would act upon conversations have an exception in the trigger rules for “Created via API” or are temporarily turned off during migration.
Batch Testing
At this point you should have a working version of the migration script setup and can begin testing by migrating a subset of sample data into your TEST workspace.
Thoroughly check the results from these tests and collaborate with your IE to make adjustments as needed.
If you’ve purchased a migration package from Intercom Customer Implementation Services and we’re doing this on your behalf - we’ll only ask you to validate the results and we’ll make any necessary updates!
Cutover
How you plan to approach migrating open tickets in Zendesk will impact how you plan the timeline for your cutover.
Drain and Fill:
In this approach you would cutover to Intercom before your official launch date so that all new support requests are going into Intercom. Your support team would work out of both platforms until all remaining open tickets in Zendesk are closed.
After closing all remaining Zendesk tickets is when you would run your final migration batch. In effect this approach doesn’t migrate open tickets at all, but instead waits for all tickets to be closed in Zendesk before moving them over.
Live Cutover:
In this approach your teams would sync the cutover to Intercom to line up with when you would run the final migration containing only open tickets.
This approach requires much greater coordination than drain and fill as everything will need to be repointed to Intercom as open tickets are being migrated in.
Zendesk Relevant API endpoints (for retrieval)
Intercom Relevant API endpoints (for creation)
Migration
The plan is concrete, the migration script is finished and fine tuned, now it is time to transfer your data!
Keep in mind:
It’s important to create a “Run Book” (and “Roll Back Plan”) of the steps for both the First Migration Run (all closed tickets up to a certain date & time) and the Formal Cutover + Delta Migration Run.
Make sure you’ve thought through a plan for what components of the migrated tickets should be visible to them (and where) plus any notifications that they should receive. Usually our clients want as little impact or visibility to their customers as possible during the migration itself, but an enhanced experience post-migration.
Post-migration, validate your ticket data and you’re done! 🎉
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts