> ## Documentation Index
> Fetch the complete documentation index at: https://help.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cómo importar contactos a CloudTalk desde un archivo

> Una guía sencilla para importar contactos a CloudTalk desde un archivo de Excel/CSV

<Note>
  En este artículo te guiaremos para subir un archivo de contactos a CloudTalk.
</Note>

**Nivel de usuario**:

* Administrador

***

<Warning>
  ⚠️ **La importación de contactos mediante archivos CSV puede tardar un tiempo.** Para obtener los mejores resultados, te recomendamos prever tiempo de procesamiento adicional en las horas punta.

  Si el tiempo es crítico para tu importación, valora otros métodos, como una integración con un CRM o la API de CloudTalk para la sincronización en tiempo real.

  📘 **Más información**: [¿Cómo importo contactos a CloudTalk?](/es/articles/2145547-how-to-import-contacts-into-cloudtalk)
</Warning>

<h2 id="data-preparation">
  Preparación de los datos
</h2>

<Warning>
  Se admite **un máximo de 8MB (normalmente \~ 80k contactos)** . Los archivos más grandes no se subirán.
</Warning>

Al importar contactos desde un archivo, actualmente requerimos el formato **`.csv`** . Hay varios tipos de software que te permiten guardar tus datos como CSV. En el caso más habitual, el de Excel, puedes ir a **Archivo > Guardar como**. En el campo *Nombre del archivo*, selecciona el formato **CSV** .

Es muy importante configurar tu archivo CSV según nuestra **plantilla de archivo CSV**. Para acceder a esta plantilla, en tu cuenta de **[CloudTalk Dashboard](https://dashboard.cloudtalk.io/)** ve a ***Contactos*** *> **Lista** > **Importar contactos en masa*** y luego haz clic en **Descargar plantilla** en la esquina inferior izquierda. Ten en cuenta que puedes eliminar sin problema de la plantilla cualquier columna que no uses.Si solo necesitas importar datos básicos como el **nombre**, el **teléfono** o el **correo electrónico**, puedes eliminar todas las demás columnas sin ningún problema.

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/2dadc89fbf39-screenshot-2026-03-18-at-11-36-16.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=7c677bcda4a98521e4afc2be17bbe2fe" alt="" width="1258" height="824" data-path="images/help-center/articles/3422012/2dadc89fbf39-screenshot-2026-03-18-at-11-36-16.png" />
</Frame>

<Info>
  #### Requisitos del archivo CSV

  Es **muy recomendable** que descargues y sigas la plantilla. Sobre todo, asegúrate de:

  * Escribir todos los nombres de columna en **minúsculas** (los atributos personalizados pueden variar)

  * **Evitar fuentes especiales o texto estilizado** (por ejemplo, fuentes cursivas, caligráficas o decorativas) en los nombres de contacto u otros campos. Pueden impedir que tu archivo se suba correctamente.

  * Usar solo **caracteres ASCII estándar** en el nombre del archivo y en el contenido. Las importaciones de CSV pueden fallar si se usan caracteres especiales o no ASCII (por ejemplo, ö, ü, ç).

  * Completar los valores de **`name`** y **`phone`** o **`email`** de **cada contacto.**

  No seguir estas pautas puede provocar filas fallidas o importaciones incompletas.\
  Algunos problemas (como encabezados o una estructura de archivo incorrectos) pueden impedir que la importación llegue a iniciarse.
</Info>

<Warning>
  **Importante: código de país predeterminado**\
  El país predeterminado configurado en tu **Configuración de la cuenta** determina qué código internacional (`+`) se aplicará automáticamente a los números de teléfono subidos que aún no lo incluyan.

  Antes de importar tu archivo, comprueba que el país seleccionado en **Cuenta > Configuración > Código de país predeterminado** coincide con el país de los números de teléfono de tu CSV.

  Si el país predeterminado es distinto, tus números pueden importarse con el prefijo internacional equivocado.
</Warning>

<h3 id="h_603d66a186">
  Ejemplo de columnas en tu hoja de cálculo
</h3>

<table>
  <tbody>
    <tr>
      <td>
        **Columna**
      </td>

      <td>
        **Descripción**
      </td>

      <td>
        **Ejemplo**
      </td>
    </tr>

    <tr>
      <td>
        `name`
      </td>

      <td>
        Nombre y apellidos del contacto. Este campo debe contener al menos un carácter.
      </td>

      <td>
        `Jane Smith`
      </td>
    </tr>

    <tr>
      <td>
        `phone`
      </td>

      <td>
        Los números de teléfono se pueden indicar en formato internacional (E.164) o en formato local. Si un número no incluye código de país, CloudTalk aplicará el código de país predeterminado de la configuración de tu cuenta.

        Para obtener los mejores resultados, se recomienda usar el formato E.164. Puedes incluir **varios números de teléfono** separados por dos puntos (`:`).
      </td>

      <td>
        `+14155550123`

        `0908678545`

        `+14155550123:+12125550189`
      </td>
    </tr>

    <tr>
      <td>
        `email`
      </td>

      <td>
        Dirección de correo electrónico principal. Puedes incluir **varias direcciones de correo electrónico** en este campo, separadas por dos puntos (`:`).
      </td>

      <td>
        [`jane.smith@company.com`](mailto:jane.smith@company.com)

        [`jane@company.com`](mailto:jane@company.com)`:j.smith@company.com`
      </td>
    </tr>

    <tr>
      <td>
        `email2`
      </td>

      <td>
        Dirección de correo electrónico adicional. Este campo se mantiene por **compatibilidad con versiones anteriores** del sistema original.
      </td>

      <td>
        [`jane.alt@company.com`](mailto:jane.alt@company.com)
      </td>
    </tr>

    <tr>
      <td>
        `title`
      </td>

      <td>
        Cargo del contacto.
      </td>

      <td>
        `Head of Sales`
      </td>
    </tr>

    <tr>
      <td>
        `company`
      </td>

      <td>
        Nombre de la empresa a la que pertenece el contacto.
      </td>

      <td>
        `Acme Corp`
      </td>
    </tr>

    <tr>
      <td>
        `address`
      </td>

      <td>
        Dirección del contacto.
      </td>

      <td>
        `Main Street 1, San Francisco`
      </td>
    </tr>

    <tr>
      <td>
        `favorite_agent`
      </td>

      <td>
        Dirección de correo electrónico de un agente de CloudTalk que se asignará como agente favorito del contacto. Si el correo coincide con un agente existente, se asigna ese agente. Si no se encuentra ninguna coincidencia, la importación de esta fila fallará.
      </td>

      <td>
        [`agent@company.com`](mailto:agent@company.com)
      </td>
    </tr>

    <tr>
      <td>
        `tag`
      </td>

      <td>
        Una o varias etiquetas para asignar al contacto. Varias etiquetas deben separarse con dos puntos (`:`). Las etiquetas existentes se reutilizan; las nuevas se crean automáticamente si no existen.
      </td>

      <td>
        `coldlead:webinar:priority`
      </td>
    </tr>

    <tr>
      <td>
        Atributos personalizados
      </td>

      <td>
        Cualquier campo adicional que quieras importar. Primero deben crearse como atributos personalizados en la Configuración de la cuenta, y los nombres de las columnas deben coincidir exactamente.
      </td>

      <td>
        `industry` → `Salud`
      </td>
    </tr>
  </tbody>
</table>

<h4 id="h_fe7c42c7f4">
  Columna de país (formatos admitidos)
</h4>

Si tu archivo CSV incluye una columna `country`, CloudTalk admite varios formatos de país para facilitar las importaciones.

Puedes usar:

* **Códigos de país de dos letras**, por ejemplo: `US`, `GB`, `DE`

* **Códigos de país de tres letras**, por ejemplo: `USA`, `FRA`, `DEU`

* **Nombres completos de países en inglés**, por ejemplo: `United States`, `Germany`, `France`

* **Variantes comunes y no ambiguas**, por ejemplo: `United States of America`, `Great Britain`, `Trinidad & Tobago`

CloudTalk normaliza automáticamente las diferencias de formato más habituales, entre ellas:

* valores en mayúsculas y minúsculas

* espacios adicionales antes, después o dentro del valor

* usar `&` en lugar de `and` (y viceversa)

Si el valor de país no se puede reconocer, la fila fallará con un mensaje de error claro que indica que el valor de país no es válido.

<h4 id="h_202c0f0772">
  Atributos personalizados
</h4>

Para asegurarte de que los campos de contacto adicionales de tu archivo CSV se muestran correctamente en los contactos, tendrás que añadirlos como *[atributos personalizados](/es/articles/2144934-custom-attributes)* en la configuración de tu dashboard.

1. En el dashboard, ve a **Cuenta > Configuración**.

2. En la pestaña *Configuración general*, desplázate hasta la sección *Contactos*.

3. Aquí es donde puedes añadir los nombres de tus campos personalizados seleccionando `+ Agregar atributo personalizado`. Asegúrate de que los nombres que introduces aquí coinciden con los de tu CSV, tanto en ortografía como en mayúsculas y minúsculas.

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/4850012ef211-screenshot-2024-12-13-at-16-49-46.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=a015e03e061b2611efa613f935921644" alt="" width="2155" height="598" data-path="images/help-center/articles/3422012/4850012ef211-screenshot-2024-12-13-at-16-49-46.png" />
</Frame>

<h2 id="importing-contacts-from-a-file">
  Importar contactos desde un archivo
</h2>

Cuando el archivo CSV esté completo y guardado en el formato correcto, ya está listo para importarse.

1. Ve a **Contactos > Lista > Importar contactos en masa.**

   <Frame>
     <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/f91509de118b-screenshot-2026-01-08-at-15-43-57.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=0eec35d6d5fb6ceea39b5c54d7e61384" alt="" width="350" data-path="images/help-center/articles/3422012/f91509de118b-screenshot-2026-01-08-at-15-43-57.png" />
   </Frame>

2. Sube el archivo CSV.

3. **Etiqueta tus contactos**: crea una etiqueta como forma de identificación para los contactos que estás importando. Esta etiqueta es importante para las [campañas del Marcador](/es/articles/8428838-setting-up-campaigns-legacy-dialer) y puede usarse para filtrar contactos.

   <Frame>
     <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/1439c01d7f67-screenshot-2024-12-13-at-14-32-52.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=5e302a417b9525143b19e4db27742204" alt="" width="330" data-path="images/help-center/articles/3422012/1439c01d7f67-screenshot-2024-12-13-at-14-32-52.png" />
   </Frame>

4. Selecciona `Confirmar` para iniciar la importación.

Después de subir el archivo, la importación aparece en **Contactos > Archivos importados**, donde puedes seguir su progreso y revisar los resultados.

<h3 id="h_8ecaab147c">
  Archivos importados
</h3>

CloudTalk guarda un historial claro de todas las importaciones de CSV para que puedas saber fácilmente qué ha pasado, detectar problemas y resolverlos sin contactar con atención al cliente.

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/fb7aedb0243a-screenshot-2026-01-08-at-17-01-15.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=3d5d8da94cc5adcf32045b1a36a8b883" alt="" width="2398" height="488" data-path="images/help-center/articles/3422012/fb7aedb0243a-screenshot-2026-01-08-at-17-01-15.png" />
</Frame>

Cuando abres una tarea de importación, CloudTalk muestra un desglose detallado que incluye:

* Número total de filas del archivo

* Número de contactos importados correctamente

* Número de contactos que han fallado (si los hay)

* Un estado fila por fila con mensajes de resultado claros. Cada fila fallida incluye un motivo concreto que explica por qué no se pudo importar el contacto.

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/661d3101fb1a-screenshot-2026-01-08-at-14-47-34.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=83f8e6224f56f95c8f949e3db3f1e927" alt="" width="2852" height="1139" data-path="images/help-center/articles/3422012/661d3101fb1a-screenshot-2026-01-08-at-14-47-34.png" />
</Frame>

<h2 id="h_bb7f784856">
  Qué ocurre si falla una importación
</h2>

<h3 id="h_3e4dc60c74">
  Errores globales de importación
</h3>

Si la importación falla antes de procesar las filas, verás un mensaje de error global que explica el motivo, por ejemplo:

* No se ha podido cargar el archivo

* Interrupción temporal del servicio (suele resolverse sola al cabo de un rato. Si el problema persiste o se repite varias veces en pocas horas, la [atención al cliente de CloudTalk](mailto:support@cloudtalk.io) puede ayudarte a investigarlo)

* El tamaño del archivo supera los 8 MB

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/fb6879d5840a-screenshot-2026-03-18-at-15-45-34.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=b108cea23b1f53953bc1068920aacff3" alt="" width="500" data-path="images/help-center/articles/3422012/fb6879d5840a-screenshot-2026-03-18-at-15-45-34.png" />
</Frame>

<h3 id="h_21e352821e">
  Importaciones parciales
</h3>

CloudTalk ya no rechaza todo el archivo por un único contacto no válido.

* Los contactos válidos se importan correctamente

* Los contactos no válidos se marcan como **Fallido**

* Una importación con este resultado se muestra con un **estado "Completado" en naranja**, que indica que la importación terminó pero algunas filas fallaron.

* Si fallan demasiadas filas (el umbral es de **1000** registros fallidos), la importación puede detenerse para evitar datos incorrectos.

Puedes descargar el informe de errores, corregir solo las filas fallidas y volver a subirlas.

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/2b0125eb2640-screenshot-2026-01-08-at-15-10-53.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=2ea927d02e569d430aa07eaecfcfe2a5" alt="" width="2416" height="1176" data-path="images/help-center/articles/3422012/2b0125eb2640-screenshot-2026-01-08-at-15-10-53.png" />
</Frame>

<h3 id="h_f4f028935e">
  Cómo corregir las filas fallidas
</h3>

1. Abre **Contactos > Archivos importados**

2. Haz clic en **Ver detalles** en la importación fallida

3. Revisa el motivo del fallo de cada contacto

4. Descarga el informe de errores (si está disponible)

5. Corrige solo las filas fallidas de tu CSV

6. Vuelve a subir el archivo corregido

<h3 id="h_9a3fafc70c">
  Lista de errores de filas fallidas y cómo solucionarlos
</h3>

<table>
  <tbody>
    <tr>
      <td>
        **Nombre del error**
      </td>

      <td>
        **Descripción**
      </td>

      <td>
        **Cómo corregirlo**
      </td>
    </tr>

    <tr>
      <td>
        `The value X in column Y is not a valid phone number.`

        `[phone, columnIndex]`
      </td>

      <td>
        El número no es un número de teléfono local o internacional válido.
      </td>

      <td>
        Introduce un número de teléfono válido en formato internacional (p. ej. `+14155550123`) o en formato local con el país predeterminado correcto configurado.
      </td>
    </tr>

    <tr>
      <td>
        `The value X in column Y is not a valid email address.`

        `[email, columnIndex]`
      </td>

      <td>
        El valor indicado no es un correo electrónico válido.
      </td>

      <td>
        Introduce un formato de correo electrónico válido (p. ej. [firstName\_lastName@gmail.com](mailto:firstName_lastName@gmail.com))
      </td>
    </tr>

    <tr>
      <td>
        `The [columnName] value in column 1 is required.`
      </td>

      <td>
        Falta una columna obligatoria o está vacía.
      </td>

      <td>
        Comprueba que no haya espacios adicionales en los encabezados de columna y asegúrate de que las columnas obligatorias tienen el nombre correcto y están completadas.
      </td>
    </tr>

    <tr>
      <td>
        `The X value in column Y is required.`

        `[fieldName, columnIndex]`
      </td>

      <td>
        Estás intentando subir el contacto sin el número de teléfono ni el correo electrónico.

        Para que CloudTalk importe este contacto, es obligatorio el campo **`phone`** o **`email`**.
      </td>

      <td>
        Revisa el contacto y asegúrate de que se indica al menos un identificador válido (número de teléfono en formato E.164 o dirección de correo electrónico).
      </td>
    </tr>

    <tr>
      <td>
        `The provided X value in column Y exceeds the maximum length of N characters.`

        `[fieldName, columnIndex, max]`
      </td>

      <td>
        Se ha superado el número máximo de caracteres permitido para una columna.
      </td>

      <td>
        Acorta el valor para que se mantenga dentro del límite de caracteres permitido para este campo.
      </td>
    </tr>

    <tr>
      <td>
        `The provided X value in column Y must be at least N characters long.`

        `[fieldName, columnIndex, max]`
      </td>

      <td>
        El número de caracteres indicado está por debajo de la longitud mínima.
      </td>

      <td>
        La columna **`name`** debe contener al menos 1 carácter. Este campo es obligatorio.

        Todos los demás campos (como **`company`**, **`website`**, **`title`**, **`industry`**, **`address`**, **`city`**, **`zip`**, etc.) son opcionales.

        Si dejas vacío algún campo opcional, no se importará ningún valor para ese campo.
      </td>
    </tr>

    <tr>
      <td>
        `The value X in column Y is not a valid website address.`

        `[columnName]`
      </td>

      <td>
        El valor de la columna website no es una dirección web válida.
      </td>

      <td>
        Revísalo y vuelve a subir una dirección web válida.
      </td>
    </tr>

    <tr>
      <td>
        `The value X in column Y is invalid.`

        `[displayFieldName, columnIndex]`
      </td>

      <td>
        Este es un error genérico. El valor de la columna no es válido.
      </td>

      <td>
        Revisa el valor de este contacto y corrige cualquier error evidente. Si no sabes cómo solucionarlo, contacta con nuestro [equipo de atención al cliente](mailto:support@cloudtalk.io).
      </td>
    </tr>
  </tbody>
</table>

<h4 id="h_fae39d618e">
  Longitud máxima de caracteres
</h4>

| Campo | Caracteres máximos |
| - | - |
| `name` | 150 |
| `zip` | 15 |
| `title` | 255 |
| `company` | 100 |
| `industry` | 100 |
| `website` | 100 |
| `address` | 255 |
| `city` | 255 |

Si un valor supera la longitud máxima, reduce el número de caracteres y vuelve a subir el archivo.

Todos los demás campos son opcionales. Si dejas vacío un campo opcional, no se importará ningún valor para ese campo.

<Warning>
  Si sigues teniendo problemas después de corregir las filas fallidas o quieres ayuda con otros síntomas concretos de la importación, consulta estas guías de resolución de problemas:

  * **[Importación de CSV bloqueada](/es/articles/12958920-csv-import-stuck)** – explica por qué una importación puede permanecer en *Procesando* durante mucho tiempo, cuándo es normal y cuándo hay que actuar.

  * **[Error al subir el archivo CSV](/es/articles/12930295-upload-of-csv-file-fails)** – repasa los problemas habituales de formato y estructura (como la codificación, encabezados que faltan o delimitadores incorrectos) y cómo resolverlos.
</Warning>

***

*¿Necesitas ayuda o tienes alguna pregunta?* Escríbenos a través de nuestro [Portal de atención al cliente](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884) — estamos aquí para ayudarte.


## Related topics

- [La carga del archivo CSV falla](/es/articles/12930295-upload-of-csv-file-fails.md)
- [Los contactos duplicados se comportan de forma inesperada](/es/articles/12929922-duplicate-contacts-behave-unexpectedly.md)
- [La importación de CSV se queda bloqueada](/es/articles/12958920-csv-import-stuck.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.