​

Descripción general

Una Suscripción representa un canal específico a través del cual un usuario puede recibir mensajes—como una dirección de email, número de teléfono o dispositivo. OneSignal soporta cuatro tipos de Suscripciones:

• Email – para enviar mensajes de email
• SMS – para enviar mensajes de texto
• Web Push – para notificaciones push vía navegadores web
• Mobile – para notificaciones push, mensajes in-app y Live Activities en dispositivos móviles

Cada usuario puede tener múltiples Suscripciones. Usa el External ID para identificar al usuario a través de todas las Suscripciones. En la imagen de arriba, “userA” tiene 5 Suscripciones:

1. Mobile (iOS) creada después de instalar la app iOS. Llama a OneSignal.login para establecer el External ID y vincular la Suscripción al usuario.
2. SMS creada después del número de teléfono proporcionado dentro de la app iOS. Ver Suscripciones SMS abajo para detalles.
3. Web Push creada después de suscribirse a push en el sitio web. Puede recibir notificaciones push.
4. Email creada después de que se proporcionó la dirección de email. Para enviar mensajes de email.
5. Mobile (Android) creada después de instalar la app Android. Puede recibir notificaciones push, mensajes in-app y Live Notifications.

---

​

Propiedades de Suscripción

Cada Suscripción tiene las siguientes propiedades:

​

Estados de suscripción

Generalmente, las Suscripciones pueden recibir mensajes (Subscribed) o no pueden recibir mensajes (Unsubscribed). Sin embargo, hay algunas excepciones: Suscripciones Mobile

• Subscribed: El usuario ha otorgado permiso para recibir notificaciones push.
  • Si tienes iOS Provisional push habilitado, entonces todas las Suscripciones móviles iOS están Subscribed hasta que el usuario las deshabilite.
• Unsubscribed: La Suscripción no puede recibir notificaciones push pero puede recibir mensajes in-app.
  • Ver Manejo de desinstalaciones, cancelaciones de suscripción y tokens push inválidos para más detalles.
• Never Subscribed – El usuario nunca otorgó permiso (igual que unsubscribed).

Suscripciones Web

• Subscribed: El usuario ha otorgado permiso para recibir notificaciones push.
• Unsubscribed: La Suscripción no puede recibir notificaciones push.
  • Ver Manejo de cancelaciones de suscripción y tokens push inválidos abajo para más detalles.

Suscripciones Email

• Subscribed: El usuario debería haber proporcionado consentimiento para recibir mensajes de email y la dirección de email es válida.
• Unsubscribed: El usuario optó por no recibir emails pero puede ser sobrescrito si es necesario.
  • Ver Suscripciones Email abajo para más detalles.

Suscripciones SMS

• Subscribed: El usuario debería haber proporcionado consentimiento para recibir mensajes SMS y el número de teléfono es válido.
• Unsubscribed: El usuario optó por no recibir mensajes SMS.
  • Ver Suscripciones SMS abajo para más detalles.

---

​

notification_types

Indica la capacidad de la Suscripción para recibir mensajes, incluyendo razones de fallos. Actualizado automáticamente vía nuestros SDKs frontend o manualmente vía API. Visible vía View User API o Export CSV.

Definiciones de Notification Types.

1 o número positivo = Subscribed.

• La Suscripción puede recibir mensajes en este canal.
• Puede usarse con la propiedad enabled si estás habilitando mensajes en nombre del usuario. Para Suscripciones push, aún debe establecerse un token válido para recibir notificaciones push. Ver nuestros docs de configuración SDK para detalles.

0, -99 = Never Subscribed.

• La Suscripción aún no se ha suscrito al canal.

-2 = Unsubscribed.

• La Suscripción no puede recibir mensajes en este canal.
• Puede usarse con la propiedad enabled establecida en false si estás desactivando mensajes en nombre del usuario. Valor recomendado al desactivar permisos de mensajes.
• Establecido automáticamente cuando el usuario cancela su suscripción.

-3, -5 = Android Support Library Error.Agrega o actualiza la Android Support Library de tu app.-4, -8, -11, -12 = Android Google Play Services Library Error.

• Verifica el logcat. Ver Obtener un Debug Log.
• Actualiza tu Google Play Services Library en tu app y verifica el logcat de la app para errores de Google Play Services. Ver Obtener un Debug Log.

-6 = Android Invalid Google Project Number.

• El FCMv1 Sender ID no coincide con el original al que pertenece este token. Verifica el logcat de la app. Ver Obtener un Debug Log.

-7, -9 = Android Outdated Google Play Services App

• Actualiza o habilita la app Google Play Services en el dispositivo.

-10 = Not Subscribed.

• La Suscripción Push desinstaló la app o canceló la suscripción en las configuraciones del dispositivo.
• Web push bloqueó notificaciones, limpió todos los datos y workers.

-13 = iOS missing_push_capability.

• Revisa los docs de configuración SDK para asegurarte de que todos los pasos estén implementados. Ver Configuración de canal.

-14, -16, -17 = iOS APNS Errors.

• El dispositivo tiene un problema conectándose a APNS. Consulta la guía Solución de problemas iOS y Obtener un Debug Log.

-15 = iOS Simulator Error.

• iOS Simulator requiere iOS 16.4+ Usa un simulador o dispositivo diferente.

-18 = Never Prompted.

• La Suscripción nunca fue solicitada para suscribirse. Esto solo rastrea el prompt de permiso requerido y no incluye mensajes in-app.

-19 = Prompted But Never Answered.

• La Suscripción fue solicitada pero no proporcionó una respuesta.

-20, -21 = temp_web_record. Web, permiso pushSubscriptionchange revocado-22 = Manually Unsubscribed via dashboard.

• El permiso fue revocado.

-23, -24 = Web Service Worker Error.

• Ver Solución de problemas Web SDK.

-31 = Disabled via REST API.-98 = SMS Subscription awaiting double opt-in.

---

​

Suscripciones Mobile

Las Suscripciones Mobile representan dispositivos iOS, Android, Huawei o Amazon y soportan:

• Notificaciones push
• Mensajes in-app
• Live Activities

Se crean automáticamente cuando un usuario instala y abre tu app con el OneSignal SDK.

​

Actualizar Suscripciones móviles

Se recomienda actualizar las propiedades de Suscripción Mobile vía el OneSignal mobile SDK.

• Solicitar permisos push y observar cambios de permiso/Suscripción
• Login usuarios para establecer External ID y Aliases
• Agregar Tags
• Establecer Language

Puedes actualizar tags, idioma y algunas otras propiedades vía la función CSV Import. Las Suscripciones Mobile también pueden crearse y actualizarse vía las APIs Users y Subscriptions, pero se recomienda el SDK móvil para la mayoría de casos de uso.

​

Manejo de desinstalaciones, cancelaciones de suscripción y tokens push inválidos

Las Suscripciones Mobile dejan de recibir notificaciones push si el usuario:

• Desinstala la app
• Deshabilita push en las configuraciones del dispositivo y nunca reabre la app
• El token push expira

En estos casos, el estado de Suscripción se establecerá como Unsubscribed al enviar notificaciones push. Ver abajo ¿Cuándo se actualizan los estados de Suscripción push? para más detalles.

• Si el usuario reinstala la app en el mismo dispositivo o nuevo dispositivo, se creará una nueva Suscripción y necesitarán resuscribirse para recibir mensajes.
• Si el usuario rehabilita push en las configuraciones del dispositivo, el estado de Suscripción se establecerá como Subscribed y un token push se actualizará cuando abran la app.
• Si el token push expira, el estado de Suscripción y nuevo token push se actualizarán cuando el usuario abra la app en el mismo dispositivo.

Rastrea cambios vía:

• Event Streams - detecta cancelaciones de suscripción al enviar push
• Reportes push - detecta cancelaciones de suscripción al enviar push
• Usa el Subscription change listener del SDK - detecta cancelaciones de suscripción cuando el usuario deshabilita push en configuraciones del dispositivo y luego abre la app

---

​

Suscripciones Web push

Las Suscripciones Web push están vinculadas a un dispositivo específico, navegador y perfil de navegador. Un usuario que se suscribe en Chrome escritorio no recibirá push en Chrome móvil a menos que también se suscriba a tu sitio web desde ese dispositivo móvil—creando una Suscripción web push separada. Las nuevas Suscripciones web push se crean en estos escenarios:

• El usuario se suscribe a tu sitio web haciendo clic en “Allow” en el prompt de permiso nativo a nivel de sistema del navegador. Esto genera un token push único y Subscription ID.
• El usuario limpia datos del navegador (historial, caché, cookies, almacenamiento local) y revisita tu sitio. Esto resulta en la creación de un nuevo Subscription ID único.

​

Actualizar Suscripciones web push

Se recomienda actualizar las propiedades de Suscripción Web push vía el OneSignal web SDK.

• Solicitar permisos push y observar cambios de permiso/Suscripción
• Login usuarios para establecer External ID y Aliases
• Agregar Tags
• Establecer Language

Puedes actualizar tags, idioma y algunas otras propiedades vía la función CSV Import. Las Suscripciones Web push no pueden crearse vía REST API pero pueden actualizarse con las APIs Users y Subscriptions, pero se recomienda el web SDK para la mayoría de casos de uso.

​

Manejo de cancelaciones de suscripción y tokens push inválidos

Las Suscripciones Web push dejan de recibir notificaciones push si el usuario:

• Limpia datos del navegador (historial, caché, cookies, almacenamiento local)
• Deshabilita push en las configuraciones del sistema del navegador
• El token push expira

En estos casos, el estado de Suscripción se establecerá como Unsubscribed al enviar notificaciones push. Ver abajo ¿Cuándo se actualizan los estados de Suscripción push? para más detalles.

• Si el usuario regresa al sitio después de limpiar datos del navegador, se creará una nueva Suscripción y se resuscribirán automáticamente para recibir mensajes si tienes auto-resubscribe habilitado.
• Si el usuario rehabilita push en las configuraciones del navegador, el estado de Suscripción se establecerá como Subscribed cuando regresen al sitio.
• Si el token push expira, el estado de Suscripción y nuevo token push se actualizarán cuando el usuario regrese al sitio.

Track changes via:

• Event Streams - detect unsubscribes when sending push
• Push reports - detect unsubscribes when sending push
• Use the SDK’s Subscription change listener - detect unsubscribes when user disables push then returns to the site

---

​

Email Subscriptions

Email Subscriptions are based on the email address and used only for email delivery. This is different from setting a Tag. Create Email Subscriptions via:

1. SDK addEmail method or email prompt - use these methods after calling OneSignal.login to set the External ID and link the Subscription to the user.
2. Create user API or Create email API
3. Dashboard CSV Importer or manually add email addresses

​

Managing email Subscriptions

Link to a user Make sure to set the external_id when creating email Subscriptions to link them to a User.

• Using the SDK, call the login method before calling addEmail to set the external_id and link the email Subscription to the user.
• Using the CSV Importer or REST API, set the external_id identifier with the email.

Subscription statuses Newly created email Subscriptions will automatically be set to Subscribed unless otherwise specified. Email Subscriptions can become unsubscribed when:

• Sending emails, the user opts-out via the Unsubscribe link
• Setting enabled to false via the API
• Using the dashboard to unsubscribe the Subscription via the options button Email Subscriptions can become resubscribed via:
• Setting enabled to true via the API
• Using the dashboard to subscribe the Subscription via the options button

If a user unsubscribes from emails, you can keep them as unsubscribed but send them important emails by sending to unsubscribed emails.

---

​

SMS Subscriptions

SMS Subscriptions are tied to E.164 formatted phone numbers. Created via:

1. SDK addSms or SMS prompt - use these methods after calling OneSignal.login to set the External ID and link the Subscription to the user.
2. Create user or Create SMS API
3. CSV Importer

​

Manage SMS Subscriptions

• User unsubscribes by replying with “STOP” or other SMS consent keywords
  • The user can also resubscribe by replying with “START” or other SMS consent keywords
• Update Subscription via API enabled property

---

​

Importing or migrating Subscriptions

Import push tokens, email addresses, and phone numbers from another provider using:

• Create user API
• Create Subscription API

---

​

Delete Subscriptions

Subscriptions can be deleted for:

• Data privacy
• Cleaning up inactive records

See Delete users for details.

---

​

FAQ

​

When do push Subscription statuses update?

Push Subscription statuses are updated:

1. When the user opens the app, the OneSignal SDK will check if the push token is valid and if notification permissions are granted, then update the Subscription status accordingly.

• You can capture this event with our SDK Subscription Observer methods and send to your Database.

2. After sending 2+ notifications to the Subscription. Use Event Streams to detect unsubscribes when sending messages.

Example:

• Message 1: Delivered. User receives on device, then user unsubscribes in device settings.
• Message 2: Delivered (but device doesn’t receive).
• Message 3: Fails (marked unsubscribed)
• Message 4: Not sent to the Subscription.

​

If a user turns off notifications in their device settings and never opens the app again, what happens?

When users turn off notifications in the device settings they can no longer receive push notifications on that device. They will be marked as unsubscribed after sending notifications to the device. See When do push Subscription statuses update? for more details.

---