Importar dados de outra plataforma (Intercom e Freshdesk)

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:

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:

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
• Integrações
• Conta, agentes e equipes
• Logs de auditoria
• Visão geral de Administração