Saltar al contenido principal
Importa o actualiza usuarios de forma masiva a través del panel de OneSignal usando un archivo CSV o entrada manual. Los casos de uso comunes incluyen migrar usuarios desde otra plataforma, actualizar detalles de usuarios y organizar usuarios con Etiquetas y Segmentos.
También puedes actualizar o crear usuarios a través de la REST API.

​
Importación CSV

Usa un archivo CSV para importar o actualizar direcciones de correo electrónico, números de teléfono, IDs externos, Etiquetas, idioma, zona horaria, país y más.

​
Requisitos del CSV

Asegúrate de que tu archivo .csv cumpla con los siguientes requisitos:
  • Codificación UTF-8 (sin BOM)
  • Sin caracteres no imprimibles (sin caracteres especiales o no-ASCII)
  • Encabezados de columna limpios y únicos
  • Tamaño de archivo menor a 150MB (aproximadamente 2 millones de filas)
  • Al menos un identificador de los siguientes:
    • external_id — Recomendado. Identifica Usuarios en todas las Suscripciones.
    • email — Requerido para crear nuevas suscripciones de correo electrónico. Consulta Validación de dirección de email para más información.
    • phone_number — Requerido para crear nuevas suscripciones de SMS.
    • subscription_id — Solo recomendado para casos en los que ya rastreas IDs de Suscripción de OneSignal en tu backend.
Solo se permite un identificador de cada tipo por fila. Para asociar múltiples correos electrónicos o números con el mismo usuario, usa filas separadas que compartan el mismo external_id.
  • Incluye external_id para desduplicar usuarios. Asegúrate de que coincida con el ID usado en el método SDK login — de lo contrario, se restablecerá cuando el usuario abra la aplicación.
  • Para cambiar el estado de suscripción, la fila debe incluir email, phone_number o subscription_id. Solo external_id no es suficiente.
  • subscription_id no vincula ni fusiona Suscripciones. Usa external_id para agregar nuevos correos electrónicos o números de teléfono a un usuario existente.

​
Columnas CSV disponibles

​
external_id
Cualquier valor alfanumérico único
Ve ID externo para más información.
​
email
Direcciones de correo electrónico válidas
Crea una suscripción de Correo electrónico. Deduplicado si ya está presente.
​
phone_number
Números de teléfono válidos
Usa formato E.164 como +15555551234. Crea una suscripción de SMS.
​
subscription_id
UUID v4 asignado por OneSignal
Recomendado solo si ya rastreas IDs de Suscripción de OneSignal en tu backend.
​
subscribed
`yes`, `no`
Establece el estado de suscripción. Requiere email, phone_number o subscription_id en la misma fila — no se puede usar solo con external_id.
​
suppressed
`true`, `false`
false elimina el correo electrónico de las listas de supresión.
​
timezone_id
Zonas horarias formateadas IANA TZ
Ve IANA TZ.
​
country
Códigos ISO 3166-2 de 2 caracteres
Ve ISO 3166-2.
​
language
Códigos ISO 639-1 de 2 caracteres
Ve ISO 639-1.
​
Tags
Valores alfanuméricos
Hasta 1,000 etiquetas. Usa encabezados de columna como claves. Ve Etiquetas.

​
Límites y restricciones de etiquetas

Los límites de plan de etiquetas se aplican por usuario, no por aplicación. Por ejemplo, si tu plan permite 20 etiquetas por usuario y un usuario ya tiene 19, solo puedes agregar 1 más — aunque la aplicación pueda tener claves de etiqueta ilimitadas.
  • Usa el flujo de trabajo de Actualizaciones masivas de etiquetas para exportar usuarios, limpiar valores de etiquetas no deseados y volver a importar con la opción de eliminación habilitada.
  • Evita los espacios en las claves de etiqueta — usa guiones bajos en su lugar.
Claves de etiqueta reservadas y restringidas Las siguientes claves de etiqueta están reservadas y no deben usarse:
  • “user”
  • “subscription”
  • “message”
  • “template”
  • “app”
  • “org”
  • “custom_data”
  • “dynamic_content”
Si accidentalmente estableces una de estas como clave de etiqueta, elimínala a través de la API de Actualización de Usuario. Sobrescrituras y eliminaciones de etiquetas Durante una importación de CSV:
  • Las etiquetas incluidas en tu CSV se sobrescriben con el valor proporcionado.
  • Las etiquetas no incluidas en tu CSV permanecen sin cambios en el registro del usuario.
Si una etiqueta sigue presente después de la importación, verifica que:
  • La columna de encabezado contiene la clave de etiqueta.
  • La fila no contiene ningún valor.
  • Seleccionaste la opción “Eliminar etiquetas con valores en blanco” en la pantalla de Revisión.
Otras fuentes de etiquetas que se agregan Si las etiquetas eliminadas reaparecen después de la importación, puede que una integración las esté escribiendo automáticamente. Las fuentes comunes incluyen:
  • Segment
  • HubSpot
  • Journeys
  • Métodos de etiquetado del SDK
  • APIs personalizadas o pipelines ETL
Revisa los mapeos de integración y los desencadenadores de eventos para asegurarte de que no estén sobrescribiendo tus cambios de CSV.

​
Importar etiquetas desde una sola columna

En lugar de usar encabezados de columna separados para cada clave de etiqueta, puedes configurar un solo encabezado tags, con cada fila de usuario conteniendo un mapa JSON de todos los pares clave-valor entre comillas. Esto es especialmente útil si exportaste previamente un CSV con etiquetas y deseas reimportarlo sin reformatear. Ejemplo de encabezado: 
external_id,email,tags
Ejemplo de filas: Las etiquetas deben estar formateadas como un objeto JSON encerrado entre comillas. 
userA,example@email.com,"{""level"":""30"",""Color"":""teal""}"
Cuando se importa, OneSignal convierte automáticamente cada par clave-valor en etiquetas distintas para el registro de suscripción. Ejemplo: Eliminación masiva de etiquetas Para eliminar etiquetas de forma masiva, exporta tus datos actuales, borra los valores de etiqueta y vuelve a importar el CSV con la opción de eliminación habilitada.
1

Exporta tus datos

  • Navega a Audiencia > Suscripciones en el panel de OneSignal. Habilita solo las columnas ID Externo, ID de Suscripción y Etiquetas (y opcionalmente Correo electrónico o Número de teléfono).
  • Haz clic en Exportar para exportar el CSV.
Selecciona las columnas visibles para exportar
2

Borra los valores de etiqueta que deseas eliminar

Abre el CSV exportado en un editor de texto y establece los valores de cada etiqueta que deseas eliminar como una cadena vacía.Por ejemplo, una fila con valores de etiqueta antes de editar:
Fila antes de editar
userA,example@email.com,"{""level"":""30"",""color"":""teal""}"
La misma fila después de borrar los valores de etiqueta:
Fila después de borrar los valores de etiqueta
userA,example@email.com,"{""level"":"""",""color"":""""}"
Esto resultará en la eliminación de las etiquetas level y color del usuario.
3

Vuelve a importar el CSV con la opción de eliminación

  • Toma el CSV editado e impórtalo.
  • En la pantalla de Revisión, selecciona Sí para Eliminar etiquetas con valores en blanco. OneSignal elimina las etiquetas con valores en blanco durante la importación.
Pantalla de revisión con opción para eliminar etiquetas con valores vacíos
Para eliminar solo etiquetas específicas, borra los valores de esas etiquetas y deja los demás sin cambios. Solo los valores en blanco se eliminan cuando la opción de eliminación está habilitada.
¿Necesitas ayuda?
  • Prueba la sección Usa IA para revisar tu CSV antes de importar anterior.
  • Contacta a support@onesignal.com y comparte el archivo CSV que cargaste junto con una captura de pantalla del correo electrónico de confirmación. ¡Estamos felices de ayudarte!

​
Validación de dirección de email

La validación de dirección de email detecta problemas comunes en las direcciones de email antes de que lleguen a tu audiencia. Marca errores tipográficos, dominios no válidos, direcciones basadas en roles y servicios de email desechables que podrían aumentar tu tasa de rebote o dañar tu reputación como remitente.

Validación de dirección de email

Valida las direcciones de email durante la importación de CSV y en masa para reducir rebotes y proteger tu reputación como remitente.

​
Usa IA para revisar tu CSV antes de importar

Si tienes errores o preguntas sobre el formato de tu CSV, puedes describir tu problema de CSV a una herramienta de IA (como Claude, ChatGPT o similar) para limpiar o reconstruir automáticamente tu archivo antes de importar nuevamente.
Siempre prueba con una muestra pequeña (5-10 filas) antes de importar miles de registros.
Ejemplo de solicitud de IA para eliminar etiquetas no deseadas
Quiero eliminar todas las etiquetas excepto "user_name" de este CSV.

Por favor:
1. Mantén solo la columna de etiqueta "user_name".
2. Elimina todas las demás columnas de etiquetas.
3. Formatea el CSV para que coincida con los requisitos de importación de OneSignal en este documento:
   https://documentation.onesignal.com/docs/en/import

Aquí está mi CSV:
[PEGAR CSV]

​
Pasos de importación

Navega a Audiencia > Importar y haz clic en Lanzar Importador CSV.
1

Sube tu CSV

Selecciona tu archivo CSV preparado.
Pantalla de carga de archivo CSV en el panel de OneSignal
2

Mapear campos

OneSignal mapea automáticamente los encabezados de tu CSV a las propiedades conocidas. Revisa los mapeos antes de confirmar — usa external_id, email, phone_number y/o subscription_id como identificadores, no como etiquetas.
Para agregar un nuevo correo electrónico o número de teléfono a un usuario existente, debes usar external_id. No uses subscription_id — no vinculará ni fusionará suscripciones.
Pantalla de mapeo de campos mostrando encabezados de columna mapeados a propiedades de OneSignal
Si OneSignal detecta problemas de formato, corrige el CSV y vuelve a subir (recomendado) o desmarca la columna afectada para omitir su importación.
3

Revisar y confirmar

La pantalla de Revisión te permite:
  • Crear automáticamente un segmento — Agrega una etiqueta a cada usuario importado y crea un segmento coincidente. Ten en cuenta los límites de tu plan.
  • Eliminar etiquetas con valores en blanco — Elimina cualquier etiqueta con valor en blanco en el CSV. Útil para limpiar etiquetas no deseadas y mantenerse dentro de los límites del plan.
  • Configurar validación de dirección de email — Configura los ajustes de validación de dirección de email para reducir rebotes y proteger tu reputación como remitente.
Por ejemplo, con este CSV:
external_id,tag1,tag2
UserA,,"tag2value"
UserB,"tag1value",
Con “Eliminar etiquetas con valores en blanco” habilitado, tag1 se elimina de UserA y tag2 se elimina de UserB.
Pantalla de revisión con opciones para crear un segmento y eliminar etiquetas en blanco
Haz clic en Confirmar e Importar. Una pantalla de estado muestra el progreso.
La importación ha comenzado. Recibirás un correo electrónico de confirmación de contact@onesignal.com cuando finalice.

​
Confirmación por correo electrónico

Una vez que el import termine, recibirás un correo electrónico de confirmación de contact@onesignal.com con los siguientes datos. Un único Usuario puede tener múltiples Suscripciones (ej. email + push), por lo que los conteos de suscripción pueden ser mayores que el número de filas. Registro(s) de suscripción agregados — Nuevas Suscripciones de correo electrónico o SMS creadas. 0 significa que no se encontraron identificadores únicos de email o phone_number. Registro(s) de suscripción modificados — Suscripciones con datos modificados (etiquetas, propiedades, etc.). Ejemplo: 10 IDs Externos vinculados a 20 suscripciones cada uno = 200 registros modificados. Actualizaciones de suscripción omitidas — Suscripciones omitidas por la razón indicada. Si la razón es “sobre el límite de etiquetas de tu aplicación”, elimina etiquetas y vuelve a importar o actualiza tu plan. No importado — Filas que no fueron actualizadas o importadas. Causas comunes: el external_id no coincide con ninguna suscripción existente, o el email/phone_number ya existe sin nuevos datos para configurar. Nuevo segmento creado — El nombre del segmento si seleccionaste esa opción.
Correo de confirmación mostrando conteos de suscripciones agregadas, modificadas, omitidas y no importadas
En el ejemplo anterior:
  • Se crearon 100 suscripciones a partir de direcciones de correo electrónico o números de teléfono únicos que no existían en la app.
  • Se actualizaron 37,814 suscripciones (no es el conteo de Usuarios — cada usuario puede tener múltiples suscripciones).
  • 621,852 filas no fueron importadas porque sus IDs Externos no correspondían a usuarios existentes, o los correos/números de teléfono ya existían sin datos nuevos.
Segmentos solo cuentan Suscripciones suscritas. Las suscripciones no suscritas son actualizadas por el import pero no se reflejan en los conteos de segmentos. Las mejoras en la segmentación están en progreso.

​
Entrada manual

Puedes agregar manualmente las suscripciones de correo electrónico y número de teléfono del usuario a través del panel de OneSignal navegando a Audiencia > Usuarios > Actualizar/Importar usuarios > Agregar usuarios manualmente.
En la pantalla Nuevo usuario, incluye los datos que desees y selecciona Crear usuario.

​
Preguntas frecuentes

​
¿Cuánto tiempo tarda una importación CSV?

La duración depende del tamaño del archivo. La mayoría de las importaciones se completan en unos minutos. Recibirás un correo electrónico de contact@onesignal.com cuando finalice la importación — agrega esa dirección a tus contactos para asegurarte de recibirlo.

​
¿Puedo deshacer una importación CSV?

No. No hay función de deshacer integrada para las importaciones CSV. Si necesitas revertir cambios, prepara un nuevo CSV con los valores correctos y vuelve a importarlo. Para eliminaciones de etiquetas, usa el flujo de trabajo de Eliminación masiva de etiquetas.

​
¿Por qué los conteos de mi segmento no coinciden con las filas de mi CSV?

Los Segmentos solo cuentan las Suscripciones suscritas. Las suscripciones no suscritas son actualizadas por la importación pero no se reflejan en los conteos de segmentos.

​
¿Por qué mi importación mostró “no importado” para algunas filas?

Las filas se omiten cuando el external_id no coincide con ninguna suscripción existente en la aplicación, o cuando el email o phone_number ya existe sin nuevos datos para configurar. Consulta la sección de Confirmación por correo electrónico para obtener detalles sobre cada estado.

​
¿Por qué las etiquetas eliminadas siguen volviendo?

Una integración o llamada del SDK puede estar re-agregando las etiquetas después de tu importación. Las fuentes comunes incluyen Segment, HubSpot, Journeys, métodos de etiquetado del SDK y APIs personalizadas. Revisa tus mapeos de integración y los activadores de eventos.