## Visión general

El área **Configuración → Datos** trae el historial de tus clientes desde otra herramienta de
soporte a tu cuenta ConversaLabs. Tiene dos pestañas: **Importar** y **Exportar** (la exportación
todavía está marcada como **Próximamente**).

Hoy se admiten dos fuentes de integración:

| Fuente | Credencial | Campo adicional |
|---|---|---|
| **Intercom** | Clave de acceso de Intercom | — |
| **Freshdesk** | Clave de API de Freshdesk | Dominio (`acme.freshdesk.com`) |

Cada importación se ejecuta **en segundo plano**, en una cola de baja prioridad: puedes cerrar la
pantalla y seguir trabajando. Mientras está activa, la página se actualiza sola cada **5 segundos**
y muestra la etapa actual, cuánto se importó por tipo, los errores y todo lo que se omitió.

La pestaña **Importar** lista las importaciones de la cuenta, de la más reciente a la más antigua,
con el total justo encima de la lista. También incluye las importaciones de contactos por CSV
hechas desde el área de Contactos: esas no vienen de una integración y el icono de la fila muestra
**File import** al pasar el ratón.

## Requisitos previos

- Perfil de **Administrador**. Todas las acciones del área (listar, abrir, crear, reintentar,
  abandonar y descargar los CSV de registros) lo exigen.
- La capacidad **Importación de datos** (la bandera `data_import`) debe estar **habilitada en la
  cuenta**. Viene **desactivada por defecto**; sin ella, la entrada **Datos** ni siquiera aparece en
  el menú de configuración.
- **Intercom**: una clave de acceso de tu workspace. La plataforma llama a la API pública de
  Intercom (`https://api.intercom.io`, versión de API `2.15`) con esa clave.
- **Freshdesk**: el dominio de tu cuenta y una clave de API. La plataforma llama a
  `https://TU-DOMINIO/api/v2` autenticándose con la clave. El dominio debe terminar en
  `.freshdesk.com` — si escribes solo `acme`, se completa como `acme.freshdesk.com`.
- **Solo una importación de integración activa por cuenta.** Mientras haya una pendiente o en
  proceso, el botón de nueva importación queda deshabilitado.

La credencial se **guarda cifrada** (cuando el cifrado está configurado en la instalación) y
**nunca es devuelta por la API** — ni en el listado ni en el detalle de la importación.

## Paso a paso

1. Abre **Configuración → Datos** y quédate en la pestaña **Importar**.
2. Haz clic en **Importar**.
3. En **Fuente**, elige **Intercom** o **Freshdesk**.
4. Ajusta el **nombre de la importación** si quieres. El valor por defecto es *Importar Intercom*
   o *Importación de Freshdesk*.
5. Para Freshdesk, completa el **Dominio de Freshdesk** (ejemplo: `acme.freshdesk.com`).
6. Pega la **Clave de acceso Intercom** o la **Clave de API de Freshdesk**. Al salir del campo, la
   validación se ejecuta automáticamente y el campo muestra *Validando clave de acceso…*, luego
   *Clave de acceso validada.* o el mensaje del error.
7. En **Datos a importar**, **Contactos** y **Conversaciones** ya vienen marcados. Desmarca lo que
   no quieras traer; al menos uno de los dos es obligatorio.
8. Haz clic en **Importar**. El botón solo se habilita cuando la clave está validada, hay al menos
   un tipo marcado y no existe otra importación activa.
9. Se te lleva directo a la pantalla de seguimiento de la importación.

## Configuración y opciones

### Qué se importa, y en qué orden

Primero se importan los **contactos**; después las **conversaciones** (y los mensajes de cada una).
Si marcas solo uno de los tipos, se ejecuta únicamente esa etapa.

### Contactos

- **Nombre**, **correo** (normalizado a minúsculas y validado) y **teléfono** en formato E.164 — un
  número sin `+` recibe el prefijo automáticamente; lo que no quede en E.164 se descarta.
- **Identificador** = el `external_id` de origen (en Freshdesk, el `unique_external_id`).
- Un contacto con correo o teléfono se crea con el tipo **Lead**.
- Atributos personalizados creados: `intercom_contact_id` e `intercom_external_id`, o
  `freshdesk_contact_id` y `freshdesk_unique_external_id`.
- En Freshdesk el teléfono viene de `mobile` (o `phone`); otros correos, campos personalizados y
  etiquetas quedan en los metadatos de origen del contacto.
- **Deduplicación**: la plataforma busca un contacto existente por **identificador**, luego por
  **correo**, luego por **teléfono**. Si lo encuentra, actualiza ese contacto en vez de crear otro.

### Conversaciones y mensajes

- Cada conversación importada entra con el estado **Resuelta** y un identificador propio
  (`intercom:<id>` o `freshdesk:<id>`), lo que evita duplicados en una importación posterior.
- Las conversaciones se reparten en **bandejas de importación** creadas automáticamente, del tipo
  API, una por canal de origen, con nombres como **Intercom Import - Email**,
  **Intercom Import - WhatsApp** o **Freshdesk Import - Phone**. Nacen con la **asignación
  automática desactivada**.
  - Intercom: Email, Instagram, Facebook, SMS, Twitter, WhatsApp, Phone, Messenger y Unknown.
  - Freshdesk: Email, Phone, Forum, Twitter, Facebook, Portal, Chat, Mobile, Ecommerce, Bot,
    WhatsApp, Internal task, Instagram, SMS y Unknown.
- **Entrante o saliente**: un mensaje es *entrante* cuando el autor en el origen es un contacto, un
  usuario o un lead, y *saliente* en los demás casos. Una nota interna del origen se convierte en
  **nota privada**.
- **Los eventos de Intercom se convierten en mensajes de actividad** en la línea de tiempo, en el
  idioma de la cuenta: asignación, apertura, cierre, aplazamiento, participante agregado o
  eliminado, cambio de atributo, acción personalizada y respuesta rápida. Freshdesk no tiene ese
  tipo de registro.
- El cuerpo se **sanitiza**: el HTML se convierte en texto plano.
- Atributos personalizados de la conversación: `intercom_conversation_id`, o `freshdesk_ticket_id`,
  `freshdesk_subject`, `freshdesk_status` y `freshdesk_priority`.

### Seguimiento

La pantalla de detalle muestra cinco tarjetas — **Fuente**, **Importar tipos**, **Creado**,
**Duración** e **Iniciado por** — y un bloque de **Progreso de importación**. Los contadores siguen
lo que marcaste: **Contactos** aparece cuando se incluyeron los contactos; **Conversaciones** y
**Mensajes** aparecen cuando se incluyeron las conversaciones.

La barra de porcentaje solo aparece cuando el origen informa el total. Intercom devuelve el total de
contactos y de conversaciones en la validación; **Freshdesk no devuelve totales**, así que allí el
progreso muestra únicamente cuántos registros ya entraron.

La etapa se muestra en el encabezado: **En cola**, **Importando contactos**, **Importando
conversaciones**, **Finalizando importación**, **Completado**, **Completado con errores**,
**Fallido** o **Abandonado**. Al terminar, la importación queda **Completado** cuando no se registró
ningún error y **Completado con errores** cuando hubo al menos uno.

### Errores y registros omitidos

El detalle trae dos secciones:

- **Errores** — fallos de la ejecución y conversaciones incompletas.
- **Saltar registros** — lo que se omitió o falló en un registro específico, con filtro por
  **Todos**, **Contactos**, **Conversaciones** y **Mensajes** — cada tipo muestra su propio conteo.

Cada sección muestra los **5 registros más recientes** en pantalla y un botón **Descargar CSV** con
la lista completa. Los archivos salen como `data-import-<id>-error-logs.csv` y
`data-import-<id>-skip-logs.csv`, con las columnas `created_at`, `kind`, `source_object_type`,
`source_object_id`, `error_code`, `message` y `details`.

El campo `kind` indica qué pasó:

| `kind` | Significado |
|---|---|
| `skipped` | Registro omitido a propósito (por ejemplo, ya importado antes) |
| `failed` | Registro que dio error y no entró |
| `incomplete` | El origen devolvió menos partes de la conversación que el total informado |
| `run_error` | La ejecución completa falló |

Motivos frecuentes de omisión: *ya importado en una importación anterior* (se reutiliza el registro
existente), *el cuerpo no tenía texto legible después de sanitizar el HTML*, *hay adjuntos pero no
se encontró texto importable* y *no había cuerpo ni adjuntos*.

### Reanudar, reintentar y abandonar

- Después de cada página procesada la plataforma guarda un **cursor**, y la siguiente página se
  encola como un nuevo trabajo. Si algo interrumpe la ejecución, esta vuelve a empezar desde el
  punto guardado, sin rehacer lo que ya entró.
- Una importación sin ninguna actualización durante **15 minutos** se marca como atascada. En ese
  caso el botón **Reintentar** aparece en el encabezado del detalle y vuelve a poner la ejecución en
  la cola.
- El botón **Abandonar** está disponible mientras la importación está pendiente o en proceso y
  termina la ejecución.
- Repetir la importación del mismo origen **no duplica** registros: cada objeto de origen tiene un
  mapeo único por cuenta, proveedor y tipo.

## Casos de uso

- Migrar el historial de soporte de Intercom o Freshdesk al cambiar de herramienta, sin perder el
  contexto de los clientes.
- Traer primero solo los **contactos**, validar la base y luego ejecutar una segunda importación con
  las **conversaciones**.
- Mantener el historial antiguo consultable dentro de la plataforma, en bandejas separadas, mientras
  la atención nueva ocurre en los canales reales.
- Auditar la migración con los CSV de errores y de registros omitidos antes de apagar la herramienta
  anterior.

## Consejos, límites y buenas prácticas

- **Una importación de integración a la vez** por cuenta. Planifica el orden si tienes varias
  fuentes.
- **Los adjuntos no se descargan.** En lugar del archivo, el mensaje recibe una marca con la
  cantidad de adjuntos del origen — `[Intercom attachment skipped: 2]` o
  `[Freshdesk attachment skipped: 2]`. Los metadatos de los adjuntos quedan guardados en el
  registro.
- **Las etiquetas del origen no se convierten en labels** de la plataforma: se conservan en los
  metadatos de origen del contacto y de la conversación.
- **Los agentes del origen no se convierten en usuarios** de la cuenta. Los mensajes de agente
  entran como salientes, sin remitente vinculado.
- **Freshdesk**: el barrido de tickets tiene un tope de **300 páginas** de 100 tickets, y los
  tickets se procesan en bloques de 10. Intercom pagina 50 contactos y 10 conversaciones por vez.
- No borres las bandejas **Import** creadas por la migración — las conversaciones importadas viven
  allí.
- Ejecuta la importación en un horario de menor movimiento y revisa los CSV de registros antes de
  dar la migración por terminada.
- Si la credencial se rota o se elimina después de crear la importación, las acciones de reanudación
  responden que la credencial no está disponible — en ese caso, crea una importación nueva.

## Solución de problemas

- **No veo “Datos” en el menú de configuración.** La capacidad no está habilitada en la cuenta o tu
  perfil no es Administrador.
- **“We could not validate this Intercom access key. Check the key and its permissions.”** (o
  **“…this Freshdesk API key…”**; cuando el origen no devuelve mensaje, aparece el texto local
  *“No se pudo validar esta clave de acceso.”*) La clave es incorrecta, está vencida o le faltan los
  permisos de lectura necesarios en la herramienta de origen.
- **“Intercom could not be reached. Please try again.”** (o **“Freshdesk could not be reached…”**)
  El origen respondió con un error que no es de autenticación, o no respondió a tiempo. Inténtalo de
  nuevo en unos minutos.
- **“Enter a valid Freshdesk domain, such as acme.freshdesk.com.”** El dominio que escribiste no es
  un dominio válido de Freshdesk. Usa el subdominio de tu cuenta.
- **“Another data import is already in progress.”** Ya existe una importación pendiente o en
  proceso. Espera a que termine o abandónala.
- **El botón Importar no se habilita.** Falta validar la clave, falta marcar al menos un tipo de dato
  o hay una importación activa.
- **“This … import is no longer stalled.”** La importación volvió a avanzar antes de que hicieras
  clic en Reintentar — solo sigue observándola.
- **Terminó como “Completado con errores”.** Abre las secciones **Errores** y **Saltar registros** y
  descarga los CSV para ver exactamente qué objetos de origen no entraron y por qué.
- **El progreso de Freshdesk no muestra porcentaje.** Es lo esperado: el origen no devuelve totales,
  así que solo se muestra el número de registros importados.

## Ver también

- [Contactos: importación y segmentos](/hc/ajuda/articles/contacts-crm-contatos-import-segmentos-es)
- [Integraciones](/hc/ajuda/articles/administration-integracoes-es)
- [Cuenta, agentes y equipos](/hc/ajuda/articles/administration-conta-agentes-equipes-es)
- [Registros de auditoría](/hc/ajuda/articles/administration-auditoria-es)
- [Visión general de Administración](/hc/ajuda/articles/administration-overview-es)