Importar o actualizar usuarios en OneSignal usando cargas CSV, REST API o entrada manual. Soporta correo electrónico, SMS, etiquetas y más para la incorporación o migración sin problemas de usuarios.
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.
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.
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.
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 restringidasLas 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 etiquetasDurante 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 agreganSi 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.
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.
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 etiquetasPara 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:
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.
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!
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.
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.
Ejemplos de prompts de IA para problemas comunes de CSV
Eliminando etiquetas
Formato de etiquetas
Identificar formatos inválidos
Corregir números de teléfono
Migrar desde 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/importAquí está mi CSV:[PEGAR CSV]
Ejemplo de solicitud de IA para corregir el formato de múltiples columnas de etiquetas
Tengo múltiples columnas de etiquetas como tag_first_name, tag_last_name y tag_city.Según la documentación de importación de OneSignal, cada etiqueta debe:- Usar el prefijo tag_- Contener solo caracteres alfanuméricos y guiones bajos- Seguir los tipos de datos admitidos¿Podrías revisar mi CSV, identificar qué está formateado incorrectamente y devolver una versión corregida que cumpla con estos requisitos?Enlace a la documentación:https://documentation.onesignal.com/docs/en/import
Ejemplo de solicitud de IA para identificar formato faltante o inválido
OneSignal rechazó mi CSV durante la importación.Por favor:1. Valida mi estructura CSV.2. Identifica cualquier problema de formato (encabezados, columnas de ID, formatos de etiquetas, comillas).3. Devuelve una versión corregida que siga los requisitos en este documento: https://documentation.onesignal.com/docs/en/import#prepare-your-csvAquí está el archivo:[PEGAR CSV]
Ejemplo de solicitud de IA para corregir formatos de número de teléfono inválidos (E.164)
Mi importación está fallando porque los números de teléfono no están en formato E.164.Por favor:1. Convierte todos los números de teléfono al formato E.164.2. Mantén todos los demás campos sin cambios.3. Asegúrate de que el CSV coincida con la estructura requerida de OneSignal: https://documentation.onesignal.com/docs/en/importEjemplo de formato actual: (555) 555-1234Aquí está mi CSV:[PEGAR CSV]
Ejemplo de solicitud de IA para migrar desde otra plataforma
Estoy migrando de [Nombre de la Plataforma] a OneSignal.¿Podrías transformar este CSV para que coincida con el formato de importación de OneSignal?Incluye:- `external_id`- Cualquier etiqueta convertida con el prefijo `tag_` (si se desea)- Números de teléfono en formato E.164 (si es aplicable)Documento de referencia:https://documentation.onesignal.com/docs/en/importAquí está mi CSV:[PEGAR CSV]
Navega a Audiencia > Importar y haz clic en Lanzar Importador CSV.
1
Sube tu CSV
Selecciona tu archivo CSV preparado.
Pantalla de Importación CSV
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 usarexternal_id. No uses subscription_id — no vinculará ni fusionará suscripciones.
Pantalla de Mapeo de Campos de Importación CSV
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.
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.
Ejemplo de confirmación por correo electrónico.
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 Suscripcionessuscritas. 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.
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.
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.
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 Suscripcionessuscritas. 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.
