Saltar al contenido principal

​
Descripción general

Esta guía te guía a través de las diferentes formas de importar datos de usuarios en OneSignal. Ya sea que estés migrando desde otra plataforma o agregando nuevos suscriptores, puedes importar o actualizar Usuarios y sus Suscripciones usando:
  • SDKs — recomendado para agregar automáticamente nuevos usuarios y suscripciones push.
  • Importador CSV — mejor para importar y actualizar usuarios de forma masiva.
  • REST API — excelente para actualizaciones programáticas o automatizadas.
  • Entrada Manual — ideal para agregar o editar usuarios individuales.

La página dentro de la sección Audiencia

​
Importación CSV

Importa o actualiza suscripciones de correo electrónico y número de teléfono junto con sus etiquetas, idioma, zona horaria, país, estado de suscripción (Correo electrónico/SMS) y estado de supresión (solo Correo electrónico).

Pantalla de Importación CSV

​
Preparar tu CSV

Asegúrate de que tu archivo cumpla con los siguientes estándares:
  • Codificación UTF-8 (sin BOM)
  • Sin caracteres no imprimibles
  • Encabezados de columna limpios y únicos
  • Tamaño de archivo menor a 150MB
Abre tu archivo en un editor de texto plano como VS Code o Sublime. Vuelve a abrir con codificación UTF-8 y verifica la visualización correcta de caracteres.
Tu archivo debe incluir al menos uno de:
  • external_id — Recomendado. Identifica Usuarios en todas las Suscripciones.
  • email — Requerido para suscripciones de correo electrónico.
  • phone_number — Requerido para suscripciones de SMS.
  • subscription_id — Solo recomendado para usar cuando se agrega el ID Externo a una suscripción existente.
subscription_id se puede usar como un identificador para casos heredados, o donde tu backend rastrea este ID de Suscripción único. No se recomienda usarlo como un identificador para agregar o actualizar propiedades.
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.
  • Incluir external_id ayuda a desduplicar usuarios, soporta actualizaciones en todos los canales y habilita futuras importaciones.
  • Asegúrate de que el external_id sea único para cada usuario y sea el mismo ID configurado a través del método SDK login. De lo contrario, se restablecerá cuando el usuario abra la aplicación.

​
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
Solo para uso heredado. Usa cuando rastrees IDs de suscripción de OneSignal.
​
subscribed
`yes`, `no`
Establece el estado de suscripción para email, phone_number y subscription_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.
​
data tags
Valores alfanuméricos
Hasta 1,000 etiquetas. Usa encabezados de columna como claves. Ve Etiquetas.

​
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,[email protected],"{""level"":""30"",""Color"":""teal""}"
Cuando se importa, OneSignal convierte automáticamente cada par clave-valor en etiquetas distintas para el registro de suscripción.

​
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.
  • Eliminando etiquetas
  • Formato de etiquetas
  • Identificar formatos inválidos
  • Formato de número de teléfono
  • Datos de otra plataforma
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]
Siempre prueba con una muestra pequeña (5-10 filas) antes de importar miles de registros.

​
Acceder al importador CSV

  1. Ve a Audiencia > Importar
  2. Haz clic en Lanzar Importador CSV
  3. Sube tu CSV (arrastra y suelta o usa el selector de archivos)

​
Mapear campos

Después de subir:
  • OneSignal mapea automáticamente encabezados a propiedades conocidas.
  • Revisa los mapeos antes de confirmar.

​
Actualizar propiedades

Usa external_id, email, phone_number o subscription_id para identificar el usuario que estás actualizando. 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.

​
Manejar advertencias

Si OneSignal detecta problemas de formato:
  • Corrige el CSV y vuelve a subir (recomendado)
  • O desmarca la columna afectada para omitir su importación

​
Revisar

En la pantalla de Revisión:
  • Opcionalmente, crea un segmento para esta importación
  • Opcionalmente, elimina etiquetas con valores en blanco:
external_id,tag1,tag2
2349-wefh-h34a,,"tag 2 value"
Crear un segmento facilita y agiliza el envío de un mensaje a estos usuarios de inmediato. Sin embargo, si tu CSV ya contiene una etiqueta única, no necesitas crear un segmento aquí. Simplemente usa la etiqueta que ya configuraste para crear tu segmento.

Opciones para crear un segmento y eliminar valores de etiqueta vacíos

Después de hacer clic en Confirmar e Importar, una pantalla de estado muestra el progreso. Recibirás un correo electrónico cuando finalice la importación.
La duración de la importación depende del tamaño del archivo. Agrega [email protected] a tus contactos de correo electrónico para asegurar que recibas los correos de finalización.

​
Confirmación por correo electrónico y solución de problemas

Una vez que el CSV haya terminado de cargarse, recibirás un correo electrónico de confirmación con los siguientes datos:
  • Registro(s) de suscripción agregados
    • La cantidad de nuevas suscripciones de correo electrónico y/o SMS creadas a través de la carga CSV.
    • 0 significa que la lista no contenía identificadores únicos de email y/o phone_number para crear las suscripciones.
  • Registro(s) de suscripción modificados
    • La cantidad de Suscripciones donde algunos datos cambiaron, como etiquetas configuradas u otras propiedades.
    • Recuerda que los Usuarios pueden tener múltiples Suscripciones. Por ejemplo, si cargaste una lista de 10 IDs Externos y cada uno estaba asociado con 20 suscripciones, verás 200 registros de suscripción modificados.
  • Actualizaciones de suscripción omitidas
    • La cantidad de Suscripciones que fueron omitidas por la razón proporcionada.
    • Si cargaste un CSV de email y/o phone_number, esas Suscripciones probablemente fueron creadas.
    • Si la razón es “debido a estar sobre el límite de etiquetas de tu aplicación”, entonces necesitas eliminar etiquetas y cargar nuevamente. O actualizar tu plan.
  • No importado
    • La cantidad de filas que no fueron actualizadas o importadas.
    • Usualmente ocurre cuando:
    1. El external_id que configuraste en el CSV no existe en ninguna suscripción en la aplicación OneSignal
    2. Las suscripciones de email y/o phone_number ya existen en la aplicación OneSignal.
  • Nuevo segmento creado
    • El nombre del segmento que creaste si es aplicable.

Ejemplo de confirmación por correo electrónico.

En el ejemplo:
  • Se crearon 100 suscripciones porque las columnas email y/o phone_number incluyeron direcciones de correo electrónico y/o números de teléfono únicos que actualmente no existían en la aplicación OneSignal.
  • Se actualizaron 37814 suscripciones. Este no es el conteo de Usuarios. Recuerda que los usuarios pueden tener múltiples Suscripciones.
  • 621852 filas del CSV no fueron importadas. Ya sea porque no tenían IDs Externos que se mapearan a usuarios en la aplicación OneSignal, o los correos electrónicos y/o números de teléfono ya existían sin datos únicos para configurar.
Actualmente los Segmentos solo cuentan el número de Suscripciones suscritas. No cuentan las suscripciones no suscritas, aunque sus datos han sido actualizados.Si el conteo de tu segmento no coincide con el CSV, es porque el segmento no está contando las suscripciones no suscritas en este momento.Esto está siendo trabajado actualmente. La nueva y mejorada segmentación estará disponible a finales de 2025.
¿Sigues teniendo problemas?Contacta a [email protected] y comparte el archivo CSV que cargaste junto con una captura de pantalla del correo electrónico de confirmación. ¡Estamos felices de ayudarte!

​
Consejos comunes para la solución de problemas

Los siguientes son problemas comunes que vemos con las importaciones CSV. También recomendamos intentar la sección Usa IA para revisar tu CSV antes de importar anterior si estás teniendo problemas.

​
Límites de etiquetas

  • Tu límite de etiquetas del plan es por usuario. Puedes tener una cantidad ilimitada de etiquetas por aplicación, pero cada usuario está sujeto al límite del plan.
  • Ejemplo: Tu límite de plan es de 20 etiquetas por usuario.
    • Si el usuario ya tiene 19 etiquetas, solo puedes agregar 1 etiqueta más a ese usuario.
    • Tu aplicación podría tener 1000 combinaciones de etiquetas diferentes, pero cada usuario solo puede tener 20 a la vez.
  • Recomendación:
    • Usa la exportación CSV del panel para exportar el ID externo, etiquetas, correo electrónico y/o número de teléfono de tus usuarios.
    • Configura los encabezados CSV con las etiquetas que deseas eliminar e importa esas primero.
    • Configura un segundo CSV con las etiquetas que deseas mantener e importa esas en segundo lugar.
    • Consulta la sección Importar etiquetas desde una sola columna anterior para más detalles.

​
Sobrescrituras y eliminaciones de etiquetas

Durante una importación 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 aún está presente después de la importación, verifica que:
  • la columna de encabezado contiene la clave de la 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, una integración puede estar escribiéndolas automáticamente de nuevo. 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 activadores de eventos para asegurarte de que no estén sobrescribiendo tus cambios CSV.
¿Necesitas ayuda?

​
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.

Pantalla de agregar usuarios manualmente

En la pantalla Nuevo usuario, incluye los datos que desees y selecciona Crear usuario.