## Visão geral

A área **Configurações → Dados** traz o histórico dos seus clientes de outra ferramenta de
atendimento para a conta ConversaLabs. Ela tem duas abas: **Importar** e **Exportar** (a exportação
ainda está marcada como **Em breve**).

Duas fontes de integração são suportadas hoje:

| Fonte | Credencial | Campo extra |
|---|---|---|
| **Intercom** | Chave de acesso do Intercom | — |
| **Freshdesk** | Chave de API do Freshdesk | Domínio (`acme.freshdesk.com`) |

Cada importação roda **em segundo plano**, em fila de baixa prioridade: você pode fechar a tela e
continuar trabalhando. Enquanto ela está ativa, a página se atualiza sozinha a cada **5 segundos**
e mostra o estágio atual, o total importado por tipo, os erros e tudo o que foi ignorado.

A aba **Importar** lista as importações da conta, da mais recente para a mais antiga, com o total
logo acima da lista. Ela também inclui as importações de contatos por CSV feitas na área de
Contatos: essas não vêm de uma integração e o ícone da linha mostra **File import** ao passar o
mouse.

## Pré-requisitos

- Perfil de **Administrador**. Todas as ações da área (listar, abrir, criar, tentar novamente,
  cancelar e baixar os CSVs de log) exigem esse perfil.
- O recurso **Importação de dados** (flag `data_import`) precisa estar **habilitado na conta**.
  Ele vem **desligado por padrão**; sem ele, o item **Dados** nem aparece no menu de configurações.
- **Intercom**: uma chave de acesso da sua workspace. A plataforma chama a API pública do Intercom
  (`https://api.intercom.io`, versão de API `2.15`) com essa chave.
- **Freshdesk**: o domínio da sua conta e uma chave de API. A plataforma chama
  `https://SEU-DOMINIO/api/v2` autenticando com a chave. O domínio precisa terminar em
  `.freshdesk.com` — se você digitar apenas `acme`, ele é completado para `acme.freshdesk.com`.
- **Apenas uma importação de integração ativa por conta**. Enquanto uma estiver pendente ou em
  processamento, o botão de nova importação fica desabilitado.

A credencial é **guardada criptografada** (quando a criptografia está configurada na instalação) e
**nunca é devolvida pela API** — nem na listagem, nem no detalhe da importação.

## Passo a passo

1. Abra **Configurações → Dados** e fique na aba **Importar**.
2. Clique em **Importar**.
3. Em **Fonte**, escolha **Intercom** ou **Freshdesk**.
4. Ajuste o **Nome da importação** se quiser. O padrão é *Importação do Intercom* ou
   *Importação do Freshdesk*.
5. Para o Freshdesk, preencha o **Domínio do Freshdesk** (exemplo: `acme.freshdesk.com`).
6. Cole a **Chave de acesso do Intercom** ou a **Chave de API do Freshdesk**. Ao sair do campo, a
   validação roda automaticamente e o campo mostra *Validando chave de acesso…*, depois
   *Chave de acesso validada.* ou a mensagem do erro.
7. Em **Dados para importar**, **Contatos** e **Conversas** já vêm marcados. Desmarque o que não
   quiser trazer; pelo menos um dos dois é obrigatório.
8. Clique em **Importar**. O botão só habilita quando a chave está validada, há pelo menos um tipo
   marcado e não existe outra importação ativa.
9. Você é levado direto para a tela de acompanhamento da importação.

## Configurações & opções

### O que é importado, e nessa ordem

Os **contatos** são importados primeiro; depois as **conversas** (e as mensagens de cada uma).
Se você marcar só um dos tipos, apenas aquele estágio é executado.

### Contatos

- **Nome**, **e-mail** (normalizado para minúsculas e validado) e **telefone** em formato E.164 —
  um número sem `+` recebe o prefixo automaticamente; o que não ficar em E.164 é descartado.
- **Identificador** = o `external_id` da origem (no Freshdesk, o `unique_external_id`).
- Contato com e-mail ou telefone é criado com o tipo **Lead**.
- Atributos personalizados criados: `intercom_contact_id` e `intercom_external_id`, ou
  `freshdesk_contact_id` e `freshdesk_unique_external_id`.
- No Freshdesk, o telefone vem de `mobile` (ou `phone`); outros e-mails, campos personalizados e
  tags são guardados no metadado de origem do contato.
- **Deduplicação**: a plataforma procura um contato existente por **identificador**, depois por
  **e-mail**, depois por **telefone**. Se achar, atualiza o existente em vez de criar outro.

### Conversas e mensagens

- Cada conversa importada entra com o status **Resolvida** e um identificador próprio
  (`intercom:<id>` ou `freshdesk:<id>`), o que evita duplicar em uma nova importação.
- As conversas são distribuídas em **caixas de entrada de importação** criadas automaticamente,
  do tipo API, uma por canal de origem, com nomes como **Intercom Import - Email**,
  **Intercom Import - WhatsApp** ou **Freshdesk Import - Phone**. Elas nascem com **atribuição
  automática desligada**.
  - Intercom: Email, Instagram, Facebook, SMS, Twitter, WhatsApp, Phone, Messenger e Unknown.
  - Freshdesk: Email, Phone, Forum, Twitter, Facebook, Portal, Chat, Mobile, Ecommerce, Bot,
    WhatsApp, Internal task, Instagram, SMS e Unknown.
- **Mensagem recebida ou enviada**: é *recebida* quando o autor na origem é um contato, um usuário
  ou um lead, e *enviada* nos demais casos. Uma nota interna da origem vira **nota privada**.
- **Os eventos do Intercom viram mensagens de atividade** na linha do tempo, no idioma da conta:
  atribuição, abertura, fechamento, adiamento, participante adicionado ou removido, mudança de
  atributo, ação personalizada e resposta rápida. O Freshdesk não tem esse tipo de registro.
- O corpo é **sanitizado**: o HTML é convertido em texto puro.
- Atributos personalizados da conversa: `intercom_conversation_id`, ou `freshdesk_ticket_id`,
  `freshdesk_subject`, `freshdesk_status` e `freshdesk_priority`.

### Acompanhamento

A tela de detalhe mostra cinco cartões — **Fonte**, **Tipos de importação**, **Criado**,
**Duração** e **Iniciado por** — e um bloco de **Progresso da importação**. Os contadores seguem o
que você marcou: **Contatos** aparece quando os contatos foram incluídos; **Conversas** e
**Mensagens** aparecem quando as conversas foram incluídas.

A barra de porcentagem só aparece quando a origem informa o total. O Intercom devolve o total de
contatos e de conversas na validação; o **Freshdesk não devolve totais**, então lá o progresso
mostra apenas quantos registros já entraram.

O estágio é exibido no cabeçalho: **Na fila**, **Importando contatos**, **Importando conversas**,
**Finalizando a importação**, **Concluído**, **Concluído com erros**, **Falhou** ou **Cancelado**.
Ao terminar, a importação fica **Concluído** quando nenhum erro foi registrado e **Concluído com
erros** quando houve pelo menos um.

### Erros e registros ignorados

O detalhe traz duas seções:

- **Erros** — falhas da execução e conversas incompletas.
- **Pular registros** — o que foi ignorado ou falhou em um registro específico, com filtro por
  **Todos**, **Contatos**, **Conversas** e **Mensagens** — cada tipo mostra a sua contagem.

Cada seção mostra os **5 registros mais recentes** na tela e um botão **Baixar CSV** com a lista
completa. Os arquivos saem como `data-import-<id>-error-logs.csv` e
`data-import-<id>-skip-logs.csv`, com as colunas `created_at`, `kind`, `source_object_type`,
`source_object_id`, `error_code`, `message` e `details`.

O campo `kind` diz o que aconteceu:

| `kind` | Significado |
|---|---|
| `skipped` | Registro ignorado de propósito (por exemplo, já importado antes) |
| `failed` | Registro que deu erro e não entrou |
| `incomplete` | A origem devolveu menos partes da conversa do que o total informado |
| `run_error` | A execução inteira falhou |

Motivos frequentes de registro ignorado: *já importado em uma importação anterior* (o registro
existente é reaproveitado), *o corpo não tinha texto legível depois da sanitização do HTML*,
*existem anexos mas nenhum texto importável* e *não havia corpo nem anexos*.

### Retomar, tentar novamente e cancelar

- A cada página processada a plataforma grava um **cursor**, e a página seguinte é enfileirada como
  um novo trabalho. Se algo interromper a execução, ela recomeça do ponto salvo, sem refazer o que
  já entrou.
- Uma importação sem nenhuma atualização por **15 minutos** é marcada como travada. Nesse caso o
  botão **Tentar novamente** aparece no cabeçalho do detalhe e recoloca a execução na fila.
- O botão **Cancelar** fica disponível enquanto a importação está pendente ou em processamento e
  encerra a execução.
- Repetir a importação da mesma origem **não duplica** registros: cada objeto de origem tem um
  mapeamento único por conta, provedor e tipo.

## Casos de uso

- Migrar o histórico de atendimento do Intercom ou do Freshdesk ao trocar de ferramenta, sem perder
  o contexto dos clientes.
- Trazer só os **contatos** primeiro, validar a base e depois rodar uma segunda importação com as
  **conversas**.
- Manter o histórico antigo pesquisável dentro da plataforma, em caixas separadas, enquanto o
  atendimento novo acontece nos canais reais.
- Auditar a migração com os CSVs de erro e de registros ignorados antes de desligar a ferramenta
  antiga.

## Dicas, limites e boas práticas

- **Uma importação de integração por vez** na conta. Planeje a ordem se você tem várias fontes.
- **Anexos não são baixados.** No lugar do arquivo, a mensagem recebe uma marcação com a quantidade
  de anexos da origem — `[Intercom attachment skipped: 2]` ou `[Freshdesk attachment skipped: 2]`.
  Os metadados dos anexos ficam guardados no registro.
- **Tags e labels da origem não viram labels** da plataforma: elas são preservadas no metadado de
  origem do contato e da conversa.
- **Agentes da origem não viram usuários** da conta. As mensagens de agente entram como enviadas,
  sem remetente vinculado.
- **Freshdesk**: a varredura de tickets tem um teto de **300 páginas** de 100 tickets, e os tickets
  são processados em blocos de 10. O Intercom pagina 50 contatos e 10 conversas por vez.
- Não apague as caixas de entrada **Import** criadas pela migração — as conversas importadas vivem
  nelas.
- Rode a importação em um horário de menor movimento e confira os CSVs de log antes de dar a
  migração por concluída.
- Se a credencial for rotacionada ou removida depois de criada a importação, as ações de retomada
  respondem que a credencial está indisponível — nesse caso, crie uma importação nova.

## Solução de problemas

- **Não vejo “Dados” no menu de configurações.** O recurso não está habilitado na conta ou o seu
  perfil não é Administrador.
- **“We could not validate this Intercom access key. Check the key and its permissions.”** (ou
  **“…this Freshdesk API key…”**; quando a origem não devolve mensagem, aparece o texto local
  *“Não foi possível validar esta chave de acesso.”*) A chave está errada, expirada ou sem as
  permissões de leitura necessárias na ferramenta de origem.
- **“Intercom could not be reached. Please try again.”** (ou **“Freshdesk could not be reached…”**)
  A origem respondeu com um erro que não é de autenticação, ou não respondeu a tempo. Tente de novo
  em alguns minutos.
- **“Enter a valid Freshdesk domain, such as acme.freshdesk.com.”** O domínio digitado não é um
  domínio válido do Freshdesk. Use o subdomínio da sua conta.
- **“Another data import is already in progress.”** Já existe uma importação pendente ou em
  processamento. Espere ela terminar ou cancele-a.
- **O botão Importar não habilita.** Falta validar a chave, falta marcar pelo menos um tipo de dado
  ou existe uma importação ativa.
- **“This … import is no longer stalled.”** A importação voltou a progredir antes de você clicar em
  Tentar novamente — basta acompanhar.
- **Terminou como “Concluído com erros”.** Abra as seções **Erros** e **Pular registros** e baixe os
  CSVs para ver exatamente quais objetos de origem não entraram e por quê.
- **O progresso do Freshdesk não mostra porcentagem.** É esperado: a origem não devolve os totais,
  então só o número de registros importados é exibido.

## Veja também

- [Contatos: importação e segmentos](/hc/ajuda/articles/contacts-crm-contatos-import-segmentos-pt-br)
- [Integrações](/hc/ajuda/articles/administration-integracoes-pt-br)
- [Conta, agentes e equipes](/hc/ajuda/articles/administration-conta-agentes-equipes-pt-br)
- [Logs de auditoria](/hc/ajuda/articles/administration-auditoria-pt-br)
- [Visão geral de Administração](/hc/ajuda/articles/administration-overview-pt-br)