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#
- 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.
- 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.
- Selecciona el archivo.
- Pulsa Continuar.
Cómo preparar el archivo:
- Formatos:
.xlsx,.xlso.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.
Errores del paso 1:
| Mensaje | Causa |
|---|---|
| «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:
| Indicador | Significado |
|---|---|
| «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#
| Dato | Regla |
|---|---|
| Nombre | Obligatorio. Se recorta a 100 caracteres. Sin nombre: «Falta el nombre.» |
| Teléfono | Formato 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…»). |
| Correo | Debe ser válido («Correo inválido.»). Se guarda en minúsculas. |
| Apellidos | Hasta 150 caracteres. |
| Fecha de nacimiento | AAAA-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. |
| Edad | Entre 0 y 120. Si la fila trae fecha de nacimiento, la edad se ignora (se calcula sola). |
| Nacionalidad | Nombre del país («Colombia») o código de 2 letras («CO»). |
| Tipo de identificación | Nombre exacto del tipo (sin importar tildes ni mayúsculas). |
| Número de documento | Hasta 60 caracteres. |
| Dirección | Hasta 255 caracteres. |
| Departamento | Nombre. Debe ser del país del teléfono. Si el nombre es ambiguo: «departamento ambiguo». |
| Ciudad | Nombre. 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 texto | Hasta 255 caracteres. |
| Campo personalizado numérico | Admite coma o punto decimal. |
| Campo personalizado de lista | Debe ser una de las opciones (sin importar tildes ni mayúsculas). |
| Campo personalizado Sí / No | Acepta «sí», «no», «true», «false», «1», «0», «x», «s», «n», «yes», «verdadero», «falso». |
| Campo obligatorio vacío o inválido | La 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álido | No bloquea la fila: el valor no se guarda y se informa como aviso. |
| Campo único repetido | La 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ón | Qué hace | Por defecto |
|---|---|---|
| Tipo de contacto | Se 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#
- Verás el resumen: «Se importarán N contactos (M filas se omiten por error o duplicado)», con el tipo, metadatos y lista elegidos.
- Responde obligatoriamente: «¿El teléfono de estos contactos (los que traen uno) se considera canal de WhatsApp?»
- 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.
- No: se guarda solo como teléfono (sin canal de WhatsApp).
- Sin responder: «Responde si el teléfono se considera canal de WhatsApp para continuar.»
- 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.
- 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».
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.
<!-- 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 -->