Importar Contactos en Masa vía CSV
Este artículo explica cómo importar contactos en Cloud Chat usando CSV, proporcionando contexto sobre cuándo y por qué
usar esta función.
https://www.loom.com/share/35167101ea694bb0820b0a940e373900
Recordatorio: también es posible hacer esto automáticamente a través de la API (FAQ sobre esto aquí).
Accede a la plantilla de importación de contactos
En Cloud Chat, importar contactos es una tarea sencilla. Primero, echemos un vistazo a una plantilla de este CSV.
Accede a la sección de contactos en el menú izquierdo principal y haz clic en importar.
Aquí, es posible descargar una plantilla de CSV que ya contiene algunos ejemplos de contactos.
El CSV tiene el siguiente ejemplo:
Cada pantalla tiene su propia plantilla
Reutilizar el CSV de una finalidad en otra es la causa más común de una importación o un envío que falla. Descarga
siempre la plantilla de la pantalla en la que estás. El archivo puede tener como máximo 10 MB.
| Finalidad | Columnas de la plantilla | | --- | --- | | Importar contactos (esta pantalla) | name, email, phone_number,
company_name, city, tags | | Audiencia de campaña por email | email, name | | Audiencia de campaña por teléfono |
phone_number, name | | Importar etiquetas | name, description, color |
Detalles importantes sobre la información en el CSV
Ten en cuenta que estas son las columnas estándar del template, pero, como verás abajo, puedes agregar más columnas como
etiquetas y campos personalizados. Las columnas que Cloud Chat no reconoce ya no se convierten automáticamente en campos
personalizados: tú decides qué hacer con cada una en el paso Revisar las columnas, más abajo.
Para aprender cómo crear campos personalizados, consulta esta FAQ.
Importante: los campos que aseguran un contacto único son teléfono, email y el identificador (identifier). Es decir, al
menos uno de estos campos debe estar presente en cada contacto.
El siguiente paso es seleccionar las columnas que deseas rellenar o modificar. Pueden ser las columnas que ya están en
la plantilla o información adicional como etiquetas y campos personalizados.
Importante: las columnas que no deben ser modificadas deben eliminarse, excepto los campos verificadores — email,
teléfono o identifier.
Ahora completa la información en las columnas que quieras añadir o modificar.
Sobre celdas en blanco: el comportamiento depende del tipo de campo:
- Nombre y campos estándar: si lo dejas en blanco, el valor existente será borrado.
- Atributos personalizados (custom attributes): las celdas en blanco son ignoradas — el valor existente se preserva.
Solo los campos completados serán actualizados.
- Etiquetas (tags): no reemplazan valores, sino que agregan nuevas etiquetas al contacto. Para eliminar etiquetas en
masa, usa nuestra API de eliminación de etiquetas (FAQ aquí) o contacta a nuestro soporte.
- Email, teléfono e identifier (cuando no son la clave de match): si están en blanco, el valor existente se preserva.
Bloqueando contactos vía CSV
La columna blocked es aceptada y bloquea el contacto en el momento de la importación.
- Valores que bloquean el contacto: true, 1, yes, t, on (case-insensitive).
- Valores que desbloquean el contacto: false, 0, no, f, off.
- Celda vacía: el contacto queda desbloqueado por defecto (solo aplica para contactos nuevos; en contactos existentes,
una celda vacía preserva el estado actual).
⚠️ Cambio reciente (a partir del 30 de abril de 2026): las cuentas que importaban CSVs con la columna blocked antes de
esa fecha tenían esa columna silenciosamente ignorada. A partir del 30/04/2026 la columna es respetada. Si dependías del
comportamiento anterior (columna ignorada), revisa tus archivos antes de re-importar.
Borrando datos vía CSV con __DELETE__
Para borrar el valor de un campo de un contacto existente, usa el valor especial __DELETE__ en la celda correspondiente:
- En phone_number, email, identifier y name: limpia el campo (queda en NULL).
- En columnas de atributos personalizados (custom_attributes): elimina la clave del objeto JSON.
- No funciona en blocked — para desbloquear un contacto, usa false en lugar de __DELETE__.
⚠️ Si por alguna razón usas literalmente la cadena "__DELETE__" como valor legítimo en algún campo, contacta al soporte
antes de la importación para evitar borrados accidentales.
Sobre los campos company, company_name y city
⚠️ Atención: los valores enviados en las columnas company, company_name y city son grabados simultáneamente en
additional_attributes y en custom_attributes. Esto garantiza que dashboards y filtros basados en cualquiera de los dos
encuentren el valor.
Cambio a partir del 30 de abril de 2026: antes de esa fecha, solo additional_attributes era poblado.
Asegúrate de que los teléfonos contengan el código internacional y el "9" delante
Un error común de nuestros clientes es olvidar incluir el código del país al agregar contactos. Para Brasil, ese código
es +55. Omitir esto puede causar duplicados. Por ello, al importar tus contactos, asegúrate de ingresar correctamente el
código del país.
Otra confusión frecuente es no poner el dígito 9 al frente de los números de teléfono, ya que actualmente todos los
celulares en Brasil llevan ese dígito inicial. Esto puede causar duplicidades no deseadas y afectar negativamente la
eficacia de tus campañas proactivas en WhatsApp.
Ej.: +5511960832431 (el +55 es el código del país y el primer 9 fue añadido por la Anatel hace unos años).
Nota técnica — normalización automática y búsqueda por variantes: el sistema cuenta con normalización automática de
teléfonos brasileños — si envías un número con +55 pero sin el 9 (ej.: +551160832431), el sistema añadirá el 9
automáticamente. Además, al identificar contactos existentes, el sistema busca también por variantes del número de
teléfono. Por ejemplo: si tu CSV envía +5511933334444 y el contacto en la base existe como +551133334444 (sin el 9), el
match se realiza igualmente y el contacto es actualizado, en lugar de crear uno duplicado. Aun así, recomendamos
firmemente que ya incluyas el 9 en el CSV para evitar cualquier ambigüedad.
Nota técnica — caracteres no imprimibles: los caracteres null-byte (\x00) presentes en cualquier celda son removidos
silenciosamente durante la importación. Importaciones que antes fallaban con ArgumentError ahora se procesan hasta el
final con la celda saneada.
¿Qué pasa en la práctica al importar contactos por CSV?
En la práctica, sucede que:
- El sistema buscará si el contacto ya existe: el sistema busca por email, identifier y teléfono en este orden de
prioridad. Si encuentra un contacto existente por cualquiera de estos campos, entenderá que se trata del mismo
contacto.
1. Si no lo encuentra, creará uno nuevo: si el email, teléfono o identifier no se encuentra, creará un contacto
nuevo.
2. Si lo encuentra, actualizará la información: los datos serán actualizados de acuerdo con las reglas de celdas en
blanco descritas arriba.
⚠️ Atención — ambigüedad entre claves (AMBIGUOUS_MATCH): si tu CSV contiene una fila cuyas claves apuntan a contactos
diferentes ya existentes en el sistema (por ejemplo, el email corresponde al contacto A pero el phone_number corresponde
al contacto B), esa fila será rechazada con el error AMBIGUOUS_MATCH para evitar pérdida de datos.
Cambio a partir del 30 de abril de 2026: antes de esa fecha, el sistema usaba el primer match encontrado (precedencia:
email > identifier > phone) y sobrescribía silenciosamente los datos del otro contacto. A partir del 30/04/2026, la fila
es rechazada para evitar la corrupción cruzada de datos. En estos casos, recomendamos corregir la divergencia
manualmente antes de re-importar.
Filas duplicadas en el CSV
Si tu CSV contiene dos o más filas con el mismo email, teléfono o identifier, solo la primera fila será procesada. Las
demás serán rechazadas como duplicadas. Esto vale incluso si las otras informaciones (nombre, etiquetas, etc.) son
diferentes entre las filas.
Consejo: antes de importar, revisa tu CSV para asegurarte de que no haya filas duplicadas referenciando al mismo
contacto.
Cómo agregar más información (columnas) como etiquetas y campos personalizados
Puedes editar cualquier información del contacto. Para ello, añade la clave del campo como título de una nueva columna.
Etiquetas (tags) — formatos aceptados
El CSV acepta tres formatos para manipular etiquetas:
- tags (recomendado): lista separada por comas. Las etiquetas se agregan al conjunto existente del contacto
(comportamiento aditivo, no reemplaza).
- tags_add: equivalente a tags. Agrega etiquetas específicas sin remover las existentes.
- tags_remove: lista separada por comas. Remueve las etiquetas indicadas del contacto.
Si en la misma fila aparecen tags_add y tags_remove con coincidencias, la remoción tiene prioridad (el orden de la
operación es: agregar primero, luego remover).
Si deseas agregar una nueva etiqueta, crea una columna y pon como título "tags" y completa cada celda con la etiqueta
que quieres agregar. En este ejemplo, agregamos la etiqueta "bug" a los contactos.
Para etiquetas, es importante que ya existan previamente. Si no, la importación fallará.
Puedes crear etiquetas directamente en la pestaña de contactos o en configuración > etiquetas.
Otra opción es completar atributos personalizados — campos que hayas creado tú mismo. Para conocer el nombre de este
campo en nuestra base de datos, ve a los atributos personalizados de contacto y copia el nombre de la clave.
Ahora subimos el import de contactos a Cloud Chat
Después de completar la hoja de cálculo, guárdala en formato CSV. Luego, vuelve a la sección de importación, selecciona
el archivo y haz clic en importar.
Revisar las columnas
Si el archivo tiene al menos una columna que Cloud Chat no reconoce, aparece un paso de revisión antes de importar. Si
todas las columnas son reconocidas, la importación empieza directo.
En ese paso decides, columna por columna:
| Acción | Qué ocurre | | --- | --- | | Ignorar | La columna no se importa. No se crea nada a partir de ella. | | Crear
nuevo campo personalizado | Crea un campo personalizado de contacto (tipo texto) con el nombre de la columna. Si ya
existe uno con la misma clave, se reutiliza. | | Asignar a una columna existente | Envía el contenido a un campo
estándar (name, email, phone_number, company_name, city, tags) o a un campo personalizado que la cuenta ya tiene. |
Las sugerencias vienen precargadas: una columna desconocida viene como Crear nuevo campo personalizado; una columna
descontinuada viene como Ignorar, con una alerta en pantalla. Dos columnas no pueden asignarse al mismo destino.
⚠️ Campos descontinuados: id, ip_address e identifier aparecen marcados como descontinuados y ya vienen con la
sugerencia de ignorar. No uses la columna id de tu herramienta anterior como identificador de contacto aquí — identifier
sigue siendo aceptado como clave de identidad, pero ya no se sugiere para bases nuevas.
ℹ️ Antes de este paso, cualquier columna no reconocida se convertía en campo personalizado sin aviso. De ahí vienen
campos como id o ip_address en la ficha de contacto de cuentas antiguas — puedes borrarlos en Configuración → Atributos
Personalizados.
Cuando el sistema complete la importación (puede tomar hasta media hora), recibirás una notificación de éxito en tu
correo, incluyendo el número de contactos importados correctamente y los fallidos.
⚠️ IMPORTANTE: asegúrate de que tu archivo CSV esté configurado con codificación UTF-8 para evitar errores en la
importación como caracteres inválidos o etiquetas no encontradas, ya que esto puede causar fallos en la importación o en
la asignación de etiquetas a los contactos.
