Inicio API e integraciones | Claves, endpoints y webhooks Migração de histórico de tickets para o Cloud Chat

Migração de histórico de tickets para o Cloud Chat

Última actualización el Sep 15, 2026

Ao migrar de outro helpdesk, as conversas antigas não vêm automaticamente — ficam na ferramenta anterior. Se quiser preservá-las no Cloud Chat, veja abaixo o que entregar pra gente.

O que você precisa nos entregar

1. Caixa de entrada pronta. Garanta que a migração do seu canal está concluída e a inbox está criada e ativa no Cloud Chat — só importamos o histórico depois disso (sem inbox, não há para onde importar).

2. O histórico no formato JSON. Exporte suas conversas antigas em um arquivo JSON com a chave conversations_data — uma lista de tickets. Cada ticket tem:

  • Datas do ticket: created_at (abertura) e updated_at (última atualização), em ISO 8601 (ex.: 2024-01-15T10:30:00Z).

  • contact: identifier (obrigatório, único e estável por cliente) e, opcionais, name, email, phone_number (E.164).

  • messages: cada mensagem com content (texto), message_type (incoming = cliente, outgoing = agente, activity = nota interna), created_at (ISO 8601) e private (true para nota interna).

  • custom_attributes (recomendado): as informações que você quer preservar como referência. Guarde o ID do ticket antigo em external_helpdesk_id (rastreabilidade), e inclua as tags e atributos do ticket que quiser manter (ex.: priority, source_queue, tags). Essas tags entram como informação/etiqueta de referência na conversa importada — não como a tag nativa que filtra na plataforma. Nos diga quais quer preservar.

Exemplo:

{
  "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. Combine o escopo com seu contato. Alinhe com a gente o período (todo o histórico ou um recorte, ex.: últimos 12 meses), quais tags/atributos quer preservar, e se quer separar por canal (WhatsApp, Instagram, e-mail…).

4. Envie o arquivo. Suba o(s) arquivo(s) .json na pasta do Google Drive que a gente compartilha com você — ou, se preferir, mande um link do arquivo (Google Drive, OneDrive, o que for). Se você quer manter os canais separados, envie um arquivo por canal (ex.: historico_whatsapp.json).

5. Comece por uma amostra. Antes do arquivo completo, mande 20–50 tickets no formato — a gente importa num ambiente de validação, você confere, e só então processamos tudo.

Não é importado: imagens e anexos. A migração é de texto (mensagens, notas internas e metadados). Se um anexo era essencial, inclua o link dele no texto da mensagem.

Regras: datas sempre em ISO 8601 (se não conseguir em UTC, nos avise o fuso); identifier único de verdade (dois clientes com o mesmo valor viram um só); arquivo em UTF-8.

A Cloud Humans faz a importação pra você

Com o arquivo enviado, o time da Cloud Humans executa a importação — importamos em lotes, respeitando os limites da plataforma, e confirmamos o resultado com você. Você não precisa mexer em API nem nos dar acesso à sua ferramenta antiga.

Prefere fazer por conta própria? Segue o passo a passo

Se seu time tem desenvolvedor e prefere rodar a importação, use a API. Além do arquivo no formato acima, você vai precisar de: API Key (ver Como pegar a sua API Key), CLOUDCHAT_DOMAIN, ACCOUNT_ID e INBOX_ID.

Endpoint

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

O corpo é o mesmo conversations_data descrito acima.

Limites — cada requisição aceita no máximo 10.000 tickets ou 15 MB. Para volumes maiores, particione em múltiplas requisições. O identifier do contato é único (dedup). Para os custom_attributes aparecerem formatados no painel, defina-os antes em Settings → Custom Attributes (escopo: Conversation).

Onde encontrar os IDs

CLOUDCHAT_DOMAIN

Parte da URL ao fazer login na sua conta:

ACCOUNT_ID

Em Configurações da conta:

API_TOKEN

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

INBOX_ID

ID da caixa que receberá os tickets. Pode ser obtido na URL da aba de configurações da inbox:

Observações