Migration guide

Import your conversation history

Moving from another chat or helpdesk tool? Export your history as a CSV or any other file, hand it to your AI assistant, and it brings every conversation into Sonny through our MCP server. It works with any tool, because your AI does the mapping.

Nothing gets sent

Imported conversations are history. Sonny doesn't email or message your customers, notify your team, fire webhooks, run AI replies or inbox rules, or send satisfaction surveys for them. They arrive closed and already read, so your inbox stays calm.

Before you start

Sonny connected to your AI assistant
Add Sonny's MCP server to Claude, Cursor or another AI app. The MCP guide takes about a minute.
An export from your old tool
A CSV, JSON or spreadsheet export of your conversations and messages. If your old tool stores files as links, keep those columns: Sonny can download them.
A channel to import into
Imported chats use the channel's website and imported emails use its email address. Your AI can list your channels and ask which one to use.

Step by step

  1. 01

    Connect Sonny

    Connect Sonny's MCP server to your AI assistant and sign in to your workspace. If you connected before today, reconnect so your AI sees the new import tool.

  2. 02

    Give it your export

    Attach the file or point your AI to it, and tell it which channel to import into.

  3. 03

    Ask it to import

    Use the prompt below as a starting point. Your AI reads the file, maps it to Sonny's format and sends it in batches.

  4. 04

    Check the results

    Your AI reports what was imported and any problems. Open a few conversations in Sonny to check they look right, then let it finish the rest.

Example prompt

Change the column names to match your file.

prompt
Import the conversations in export.csv into my Sonny channel "Support" using the import_conversations tool.
Each row is one message. Group rows by ticket_id, which is the conversation's externalId, and use message_id as each message's externalId.
Customer messages are incoming, agent replies are outgoing and private comments are notes.
Use created_at as sentAt (the times are in UTC) and attachment_url for attachments.
Import 5 conversations first so I can check them in Sonny, then import the rest in batches of 20 and show me the totals.

What comes over

Conversations
Subject, status, tags and assignee, as chat or email conversations on your channel.
Messages
Customer messages, team replies, internal notes and chatbot replies, each with its original date and time.
Contacts
Matched by email address and created when new. Contacts you already have in Sonny are never changed.
Attachments
Images, PDFs, documents, spreadsheets and ZIP files up to 25MB, from a public link or sent as the file itself.

The import format

Your AI sends conversations in this shape. You don't need to write it yourself, but it helps to know what each field does.

json
{
  "sourceId": "source_shop",
  "conversations": [
    {
      "externalId": "crisp-8812",
      "subject": "Delivery question",
      "contact": {
        "email": "ada@example.com",
        "name": "Ada"
      },
      "tags": [
        "Shipping"
      ],
      "messages": [
        {
          "externalId": "1",
          "direction": "incoming",
          "body": "Has my order shipped?",
          "sentAt": "2025-03-14T09:30:00Z"
        },
        {
          "externalId": "2",
          "direction": "outgoing",
          "body": "Yes, it left this morning.",
          "sentAt": "2025-03-14T09:41:00Z",
          "author": {
            "name": "Sam",
            "email": "sam@yourcompany.com"
          }
        },
        {
          "externalId": "3",
          "direction": "incoming",
          "body": "",
          "sentAt": "2025-03-14T09:45:00Z",
          "attachments": [
            {
              "url": "https://files.example.com/receipt.pdf"
            }
          ]
        }
      ]
    }
  ]
}
externalId
The conversation's ID in your old tool. Required. Importing the same ID again only adds what's new.
messages
The conversation's messages. Each needs a direction (incoming, outgoing or note), a body and sentAt.
sentAt
When the message was sent, in ISO 8601 with a timezone, for example 2025-03-14T09:30:00Z.
author
Who wrote it. A teammate's email links the reply to them in Sonny, and type bot marks chatbot replies.
contact
The customer's email address and name.
status
open, pending or closed. Defaults to closed.
channel
chat or email. Defaults to chat when the channel has a website.
attachments
Files, each as a public https url, or as fileName, contentType and dataBase64.
tags
Tag names. New tags are created for you.
assigneeEmail
The teammate to assign the conversation to.

Good to know

  • Safe to run again. If an import stops halfway, run it again. Messages that already came over are skipped and failed attachments are retried.
  • Batches. Each call takes up to 50 conversations, 1,000 messages and 25 attachments. Your AI splits bigger imports for you.
  • No email address? The conversation still imports, just without a contact. The customer's name stays on their messages.
  • Teammates. A reply is linked to a teammate when the author's email matches someone in your workspace. Otherwise it keeps the name from your old tool.
  • Who can import. Owners, admins and agents. API keys need write access to conversations, messages and contacts, plus attachments for files.

For developers

Not using an AI assistant? Send the same JSON to POST /api/v1/conversations/import with an API key. The API reference has the full schema.

Related docs