Ir al contenido
Documentación de Connecto
connecto.lat
Guía de usuarioContactos

Importar contactos

Para qué sirve#

Cargar muchos contactos de una sola vez desde un archivo de Excel o CSV, clasificarlos (tipo, metadatos, lista de distribución, propietario) y registrar su autorización para recibir mensajes.

Quién puede usarlo y cómo llegar#

  • Quién: administradores, supervisores y agentes. Crear metadatos y listas nuevos desde el asistente es solo para administradores y supervisores. Un agente solo puede dejarse a sí mismo como propietario.
  • Cómo llegar: Contactos > botón Importar Excel (ayuda: «Importar contactos desde Excel»).

El asistente tiene cuatro pasos y una pantalla final: 1 Archivo, 2 Columnas, 3 Clasificar, 4 Confirmar. Puedes volver con Atrás y cerrar con la X o con Esc (no se importa nada hasta el paso final).

Paso 1: Archivo#

  1. Opcional: pulsa Descargar plantilla actualizada (.xlsx). La plantilla trae una columna por cada campo activo hoy (básicos, opcionales y personalizados), dos filas de ejemplo y una hoja «Instrucciones» que explica cómo llenar cada columna. Se actualiza cada vez que abres el asistente. Usarla es opcional.
  2. Elige el país por defecto para números sin código. Aparece primero Colombia (+57), luego los demás países que tienen indicativo.
  3. Selecciona el archivo.
  4. Pulsa Continuar.

Cómo preparar el archivo:

  • Formatos: .xlsx, .xls o .csv. Se lee la primera hoja.
  • La primera fila son los títulos de las columnas; luego, un contacto por fila. Las filas totalmente vacías se ignoran.
  • Nombre es obligatorio. Teléfono y Correo electrónico son opcionales: si van vacíos, el contacto se importa sin ese dato. Si vienen mal escritos, la fila se marca con error.
  • Los campos opcionales y personalizados activos también se pueden importar. Los que tu administrador marcó como obligatorios son obligatorios también aquí (el asistente los lista).
  • Pon la columna de teléfonos en formato Texto, para que Excel no la convierta en notación científica (por ejemplo 5.73E+11).
  • Los teléfonos que ya existan en tus contactos o se repitan en el archivo se omiten.
La pantalla del asistente dice «Hasta 5000 filas por importación», pero el asistente lee archivos de hasta 400.000 filas y los envía por tandas de 4.000. Con más de 50.000 filas conviene guardar el archivo como CSV; si el archivo es demasiado pesado para leerlo como Excel, el asistente lo avisa y pide guardarlo como CSV (UTF-8) o dividirlo.

Errores del paso 1:

MensajeCausa
«El archivo no tiene filas de datos (la primera fila debe tener los títulos).»El archivo solo tiene títulos o está vacío.
«El archivo tiene N filas; el máximo por archivo es 400.000. Divídelo en varios archivos.»Se superó el máximo.
«No se pudo cargar el lector de Excel. Recarga la página.»Falló la carga del lector de archivos.

Paso 2: Columnas#

Aparece una tabla con las primeras 5 filas del archivo. Sobre cada columna hay una lista para indicar qué dato es, o «No importar».

  • Connecto reconoce solo las columnas cuyo título coincide con un campo (o se parece: «nombre», «tel», «celular», «móvil», «whatsapp», «mail», «correo», «cédula», «dirección», «cumpleaños», «ciudad», etc.).
  • Cada dato puede estar en una sola columna. Si eliges un dato ya usado, se libera de la otra columna.
  • Debajo ves «N de M columnas se importarán» y, si falta un obligatorio: «Falta indicar: Nombre (obligatorio).»
  • Pulsa Validar y continuar. Si falta alguna columna obligatoria: «Falta indicar la columna de: X (obligatorio).»

Revisión#

Tras validar (sin guardar nada) verás:

IndicadorSignificado
«N listos para importar»Filas válidas.
«N con avisos»Se importan, pero algún valor de un campo adicional no era válido y no se guardará.
«N duplicados (se omiten)»Teléfono, correo o valor único ya existente.
«N con error»Filas inválidas; no se importan.

Debajo aparece la lista de avisos («Fila 12: Fecha de nacimiento: fecha no reconocida (usa AAAA-MM-DD o DD/MM/AAAA) — no se guardó») y una tabla de problemas donde puedes corregir Nombre, Teléfono y Correo de las filas con error y pulsar Revalidar. Se muestran hasta 200 filas con problemas y 100 con avisos.

Si no hay ninguna fila válida: «No hay filas válidas para importar. Corrige los errores o revisa las columnas.»

Reglas de cada dato#

DatoRegla
NombreObligatorio. Se recorta a 100 caracteres. Sin nombre: «Falta el nombre.»
TeléfonoFormato internacional. Se aceptan espacios, guiones, paréntesis, + o 00 al inicio. Sin código de país, se le antepone el del país por defecto que elegiste. Debe tener entre 8 y 15 dígitos con el código. Si Excel lo convirtió en notación científica: «El teléfono está en notación científica (Excel lo acortó). Pon la columna en formato Texto.» Para Colombia (+57): celular 3XX XXXXXXX o fijo 60X XXXXXXX («Número de Colombia inválido…»).
CorreoDebe ser válido («Correo inválido.»). Se guarda en minúsculas.
ApellidosHasta 150 caracteres.
Fecha de nacimientoAAAA-MM-DD o DD/MM/AAAA (también DD-MM-AAAA, DD.MM.AAAA, AAAA/MM/DD) o un número de serie de Excel. No puede ser futura.
EdadEntre 0 y 120. Si la fila trae fecha de nacimiento, la edad se ignora (se calcula sola).
NacionalidadNombre del país («Colombia») o código de 2 letras («CO»).
Tipo de identificaciónNombre exacto del tipo (sin importar tildes ni mayúsculas).
Número de documentoHasta 60 caracteres.
DirecciónHasta 255 caracteres.
DepartamentoNombre. Debe ser del país del teléfono. Si el nombre es ambiguo: «departamento ambiguo».
CiudadNombre. Si no indicas departamento y la ciudad existe en varios: «ciudad ambigua: indica también el departamento». Al elegir ciudad se completa su departamento.
Campo personalizado de textoHasta 255 caracteres.
Campo personalizado numéricoAdmite coma o punto decimal.
Campo personalizado de listaDebe ser una de las opciones (sin importar tildes ni mayúsculas).
Campo personalizado Sí / NoAcepta «sí», «no», «true», «false», «1», «0», «x», «s», «n», «yes», «verdadero», «falso».
Campo obligatorio vacío o inválidoLa fila queda con error: «Falta «X» (campo obligatorio).» o ««X» inválido (motivo) y es obligatorio.»
Campo opcional o personalizado no obligatorio con valor inválidoNo bloquea la fila: el valor no se guarda y se informa como aviso.
Campo único repetidoLa fila se cuenta como duplicada: «El valor «X» del campo único «Y» ya existe en otro contacto.» (o «en otra fila del archivo.»).

Qué se considera duplicado#

  • Con teléfono: ya existe un contacto con ese número (en su teléfono, teléfonos o WhatsApp) → «Ya existe un contacto con este teléfono.»; o el número se repite en el archivo → «Teléfono repetido en el archivo (fila N).»
  • Sin teléfono pero con correo: se compara el correo → «Ya existe un contacto con este correo.» / «Correo repetido en el archivo (fila N).»
  • Los contactos eliminados y los fusionados dentro de otro no cuentan.
  • Si el archivo supera las 4.000 filas se valida por tandas; un repetido entre tandas se detecta al importar y se informa como duplicado omitido.

Paso 3: Clasificar#

Define cómo quedan los N contactos que se van a importar. Todo es opcional, salvo el tipo.

OpciónQué hacePor defecto
Tipo de contactoSe asigna a todos.El primer tipo de la lista (de fábrica, «CONTACTO»)
Metadatos (opcional)Marca uno o varios; se asignan a todos los importados, a nombre de quien importa. Nuevo metadato (solo administradores y supervisores) crea uno sin salir del asistente: Nombre (hasta 100 caracteres), Color (por defecto #10B981) y Descripción (opcional). Si no hay: «Todavía no hay metadatos creados.»Ninguno
Lista de distribución (opcional)Los contactos se agregan a una lista de distribución activa. Nueva lista (solo administradores y supervisores) la crea (Nombre hasta 150 caracteres, Descripción opcional).«No agregar a ninguna lista»
«Estos contactos aceptaron recibir correos»Registra su autorización de correo (solo a quienes traen correo). Sin autorización registrada no se les pueden enviar difusiones por correo.Desmarcada
«Estos contactos aceptaron recibir mensajes por WhatsApp»Registra su autorización de WhatsApp. Solo se aplica si en el paso 4 indicas que el teléfono es canal de WhatsApp.Desmarcada

Errores al crear: «El nombre es obligatorio.», «Ya existe un metadato con ese nombre.», «Ya existe una lista de distribución con ese nombre.»

Paso 4: Confirmar#

  1. Verás el resumen: «Se importarán N contactos (M filas se omiten por error o duplicado)», con el tipo, metadatos y lista elegidos.
  2. Responde obligatoriamente: «¿El teléfono de estos contactos (los que traen uno) se considera canal de WhatsApp?»
    1. Sí: el teléfono es también su número de WhatsApp; podrás escribirles por WhatsApp y sus mensajes entrantes llegan a este mismo contacto.
    2. No: se guarda solo como teléfono (sin canal de WhatsApp).
    3. Sin responder: «Responde si el teléfono se considera canal de WhatsApp para continuar.»
  3. Opcional: elige el propietario de los contactos (por defecto «Sin propietario»; un agente solo puede elegirse a sí mismo). Quienes queden sin propietario se pueden repartir luego desde la lista.
  4. Pulsa Importar contactos.

Resultado#

Aparece «Importación completada» con: contactos importados (y «con canal de WhatsApp» si aplica), tipo asignado, lista de distribución, autorizaciones registradas, metadatos asignados, avisos, duplicados omitidos y filas con error omitidas. Pulsa Cerrar y actualizar la lista.

Qué datos quedan en los contactos importados#

  • Estado ACTIVO.
  • Idioma y moneda: los predeterminados.
  • País: se deduce del prefijo del teléfono; si no hay teléfono o no se reconoce, queda vacío.
  • Con teléfono: se guarda con formato internacional (+57…). Si marcaste WhatsApp, el teléfono principal se guarda solo con dígitos y se registra también como WhatsApp.
  • Si elegiste propietario, queda registrado con la vía «importación».
La importación se guarda por tandas completas: si una tanda falla, aparece «No se pudo completar la importación; no se guardó ningún contacto.» y esa tanda no se guarda. En archivos grandes, las tandas anteriores ya quedaron guardadas; el mensaje de error indica cuántos se habían importado. Volver a importar el mismo archivo omite los que ya existen.

Importar desde HubSpot#

Además del Excel, los administradores pueden traer contactos y listas desde HubSpot en Conectores (menú del avatar > Conectores). El proceso corre en segundo plano.

  • Conexión: con el token de una «aplicación privada» de HubSpot con permiso de lectura de contactos (y, opcionalmente, de listas y del esquema de contactos). El token se guarda cifrado y no se vuelve a mostrar.
  • Contactos: por cada contacto de HubSpot se busca uno existente en Connecto por su id de HubSpot, luego por correo y luego por teléfono (nunca por nombre). Si existe, se completa sin pisar lo que ya tiene (agrega correos y teléfonos que falten y llena campos vacíos); si no, se crea con el tipo de contacto elegido. Los teléfonos de HubSpot sin formato válido y otros datos de HubSpot (empresa, cargo, etapa del ciclo de vida, etc.) se guardan en una nota del contacto que empieza con «Datos importados de HubSpot:».
  • Listas: las listas de contactos de HubSpot se crean como listas de distribución si no existen (por nombre) y se les asocian sus contactos.
  • Se puede detener y continuar después.
Sin verificar: los textos exactos de la pantalla de Conectores y sus botones no se revisaron en esta sección (la pantalla se documenta en Integraciones). Según el código, el proceso supone el prefijo +57 para teléfonos de HubSpot sin código de país y, si al iniciar no se indica lo contrario, trata todos los teléfonos como WhatsApp.

<!-- Fuente: tenant-app/public/api/contactos_importar.php, tenant-app/views/partials/contactos_importar_modal.php, shared/js/contactos-import.js, shared/src/Core/PhoneFormat.php, shared/src/Core/HubSpot.php, tenant-app/public/api/conectores.php, tenant-app/cli/hubspot_importar.php -->

¿Te fue útil esta página?
Última actualización: 14/11/2026