Importar datos desde otra plataforma (Intercom y Freshdesk)

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:

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ó:

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
• Integraciones
• Cuenta, agentes y equipos
• Registros de auditoría
• Visión general de Administración