Home API and integrations | Keys, endpoints and webhooks Migrating ticket history to Cloud Chat

Migrating ticket history to Cloud Chat

Last updated on Sep 22, 2026

When you migrate from another helpdesk, your old conversations do not come over automatically — they stay in your previous tool. If you want to keep them in Cloud Chat, see below what you need to send us.

What you need to send us

1. Inbox ready. Make sure the migration of your channel is complete and the inbox is created and active in Cloud Chat — we only import the history after that (with no inbox, there is nowhere to import to).

2. The history in JSON format. Export your old conversations in a JSON file with the conversations_data key — a list of tickets. Each ticket has:

  • Ticket dates: created_at (when it was opened) and updated_at (last update), in ISO 8601 (e.g.: 2024-01-15T10:30:00Z).

  • contact: identifier (required, unique and stable per customer) and, optionally, name, email, phone_number (E.164).

  • messages: each message with content (text), message_type (incoming = customer, outgoing = agent, activity = internal note), created_at (ISO 8601) and private (true for internal notes).

  • custom_attributes (recommended): the information you want to keep as a reference. Store the ID of the old ticket in external_helpdesk_id (traceability), and include the ticket tags and attributes you want to keep (e.g.: priority, source_queue, tags). These tags come in as reference information/labels on the imported conversation — not as the native tag that filters on the platform. Tell us which ones you want to keep.

Example:

{
  "conversations_data": [
    {
      "contact": { "identifier": "user_6782902", "name": "John Doe", "email": "[email protected]", "phone_number": "+5511988887777" },
      "custom_attributes": { "external_helpdesk_id": "ZD-78901", "priority": "high" },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-16T14:22:00Z",
      "messages": [
        { "content": "Meu pedido nĂŁo chegou.", "message_type": "incoming", "created_at": "2024-01-15T10:30:00Z", "private": false },
        { "content": "Oi! Já verifiquei, sai hoje.", "message_type": "outgoing", "created_at": "2024-01-15T10:31:00Z", "private": false },
        { "content": "Cliente VIP, priorizar.", "message_type": "activity", "created_at": "2024-01-15T11:16:00Z", "private": true }
      ]
    }
  ]
}

3. Agree on the scope with your contact. Align with us the time range (the whole history or a slice, e.g.: the last 12 months), which tags/attributes you want to keep, and whether you want to split it by channel (WhatsApp, Instagram, email…).

4. Send the file. Upload the .json file(s) to the Google Drive folder we share with you — or, if you prefer, send a link to the file (Google Drive, OneDrive, whichever). If you want to keep the channels separate, send one file per channel (e.g.: historico_whatsapp.json).

5. Start with a sample. Before the complete file, send 20–50 tickets in the format — we import them into a validation environment, you check them, and only then do we process everything.

Not imported: images and attachments. The migration covers text (messages, internal notes and metadata). If an attachment was essential, include its link in the message text.

Rules: dates always in ISO 8601 (if you cannot provide them in UTC, let us know the time zone); a truly unique identifier (two customers with the same value become a single one); file in UTF-8.

Cloud Humans does the import for you

Once the file has been sent, the Cloud Humans team runs the import — we import in batches, respecting the platform limits, and we confirm the result with you. You do not need to deal with any API or give us access to your old tool.

Prefer to do it yourself? Here is the step by step

If your team has a developer and prefers to run the import, use the API. Besides the file in the format above, you will need: an API Key (see How to get your API Key), CLOUDCHAT_DOMAIN, ACCOUNT_ID and INBOX_ID.

Endpoint

POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import
Header Value
content-type application/json
api_access_token Your API token

The body is the same conversations_data described above.

Limits — each request accepts at most 10,000 tickets or 15 MB. For larger volumes, split it into multiple requests. The contact identifier is unique (dedup). For the custom_attributes to show up formatted in the panel, define them beforehand in Settings → Custom Attributes (scope: Conversation).

Where to find the IDs

CLOUDCHAT_DOMAIN

Part of the URL when you log in to your account:

ACCOUNT_ID

In "Configurações da conta" (Account settings):

API_TOKEN

At https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings:

INBOX_ID

ID of the inbox that will receive the tickets. You can get it from the URL of the inbox settings tab:

Notes