Mensajes transaccionales

Enviar mensajes oportunos y personalizados a individuos o grupos pequeños es crítico para entregar una fuerte experiencia del cliente y mantener el compromiso. Los mensajes transaccionales—como Códigos de Un Solo Uso (OTPs), actualizaciones de facturación o confirmaciones de actividad—te permiten compartir actualizaciones significativas en tiempo real desde tu servidor. Esta guía explica cómo enviar mensajes transaccionales (push, email o SMS) con el API de OneSignal usando datos personalizados e identificadores de usuario.

Casos de uso comunes

Usa mensajes transaccionales para:

Enviar códigos de inicio de sesión y verificación (OTP)
Confirmar pedidos, recibos o cambios de suscripción
Entregar estado de facturación o alertas de renovación
Recordar a usuarios sobre citas o fechas límite
Reconocer acciones clave (ej. registros o compras)

Requisitos

Antes de enviar mensajes transaccionales, sugerimos revisar las siguientes guías:

Entender Users, Subscriptions y Aliases de OneSignal.
Configurar tu Database, DMP o CRM para comunicarse con OneSignal o usar una de nuestras Integrations.
Crear Templates para personalizar tus mensajes.
Usar Liquid Syntax para personalizar tus mensajes.

Identificar usuarios

Para dirigirte a usuarios individuales, debes identificarlos dentro de OneSignal. El enfoque recomendado es establecer un External ID, que debe mapear al identificador de usuario usado en tu base de datos o CRM. OneSignal también soporta hasta 20 aliases por usuario, permitiéndote asociar múltiples identificadores (ej., other_user_id, facebook_id, etc.) a través de tus sistemas. Para email y SMS, también puedes enviar mensajes directamente usando la dirección de email o número de teléfono respectivamente.

Dirigirte a usuarios

Usa el Create Message API para enviar mensajes transaccionales a través de canales de push, email y SMS dirigiéndote a usuarios vía aliases, direcciones de email, números de teléfono o IDs de suscripción.

Enviar a aliases (recomendado)

Usa include_aliases para dirigirte al external_id recomendado u otros aliases así:

{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"external_id": ["userA", "userB"]},
  "contents": {"en": "English Message"},
  "target_channel": "push"
}

{
  "app_id": "YOUR_APP_ID",
  "include_aliases": { "alias_label": ["alias_id_1", "alias_id_2"] },
  "contents": { "en": "English Message" },
  "target_channel": "email"
}

Enviar a suscripciones

Si quieres enviar a Suscripciones específicas, puedes usar la propiedad include_subscription_ids. Esta opción no se recomienda porque los Usuarios pueden tener múltiples Suscripciones.

{
  "app_id": "YOUR_APP_ID",
  "include_subscription_ids": ["1dd608f2-c6a1-11e3-851d-000c2940e62c"],
  "contents": { "en": "English Message" }
}

Enviar a direcciones de email

Si tienes la dirección de email del usuario, puedes enviarles emails usando la propiedad include_email_tokens. Cualquier email incluido que no exista dentro de tu aplicación OneSignal creará automáticamente una nueva suscripción de email.

{
  "app_id": "YOUR_APP_ID",
  "include_email_tokens": ["user1@email.com", "user2@email.com"],
  "email_subject": "Welcome to Cat Facts!",
  "email_body": "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts</h1><h4>Learn more about everyone's favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can't wait to surprise you with funny details about your favorite animal.</p><h5>Today's Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href='https://catfac.ts/welcome'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href='[unsubscribe_url]'>Unsubscribe</a></small></p></body></html>"
}

Enviar a números de teléfono

Si tienes el número de teléfono del usuario, puedes enviarles SMS y MMS usando la propiedad include_phone_numbers. Cualquier número de teléfono incluido que no exista dentro de tu aplicación OneSignal creará automáticamente una nueva suscripción SMS.

{
  "app_id": "YOUR_APP_ID",
  "include_phone_numbers": ["+15555555555"],
  "contents": { "en": "English Message" }
}

Agregar datos personalizados

Para contenido personalizado, pasa custom_data específico del usuario al mensaje usando Templates y sintaxis Liquid. Pasos para agregar datos personalizados:

Crea un Template vía el dashboard o Create template API.
Agrega Variables Liquid (ej., {{ message.custom_data.order_id }}) a tu plantilla.
Referencia el template_id y custom_data dentro de tu llamada al API Create Message.

{
  "app_id": "YOUR_APP_ID",
  "include_aliases": { "external_id": ["userA"] },
  "template_id": "8458af75-4da2-4ecf-afb5-f242a8926cc3",
  "custom_data": { "order_id": 123, "currency": "USD", "amount": 25 }
}

Ejemplo: Código de Un Solo Uso (OTP)

Identifica al usuario usando un alias, email o número de teléfono.
Crea un Template que incluya un código de verificación:

Your verification code is {{ message.custom_data.verification_code }}

Genera el verification_code en tu servidor cuando el usuario solicita acceso.
Ingresa el valor de verification_code en la solicitud del API.

{
  "app_id": "YOUR_APP_ID",
  "include_aliases": { "external_id": ["userA"] },
  "template_id": "8458af75-4da2-4ecf-afb5-f242a8926cc3",
  "custom_data": { "verification_code": "123456" }
}

Alternativa: Si no quieres usar plantillas y custom_data puedes ingresar el valor de la variable directamente en el mensaje con concatenación de cadenas. Por ejemplo:

{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"external_id": ["userA"]},
  "contents": {"en": "Your verification code is " + verification_code}
}

Solución de problemas

Para include_aliases, el alias debe estar registrado en el usuario previamente.
Para email/SMS, asegura el formato correcto.

Tutoriales

🏢 Por Industria

📈 Aumentar el compromiso y la retención

🔔 Entregar mensajes críticos o de alta prioridad

🧠 Mejorar el enfoque y la personalización

🛠️ Mejorar la experiencia del usuario y la incorporación

Mensajes transaccionales

Casos de uso comunes

Requisitos

Identificar usuarios

Dirigirte a usuarios

Enviar a aliases (recomendado)

Enviar a suscripciones

Enviar a direcciones de email

Enviar a números de teléfono

Agregar datos personalizados

Ejemplo: Código de Un Solo Uso (OTP)

Solución de problemas

Recursos adicionales

​Casos de uso comunes

​Requisitos

​Identificar usuarios

​Dirigirte a usuarios

​Enviar a aliases (recomendado)

​Enviar a suscripciones

​Enviar a direcciones de email

​Enviar a números de teléfono

​Agregar datos personalizados

​Ejemplo: Código de Un Solo Uso (OTP)

​Solución de problemas

​Recursos adicionales

Casos de uso comunes

Requisitos

Identificar usuarios

Dirigirte a usuarios

Enviar a aliases (recomendado)

Enviar a suscripciones

Enviar a direcciones de email

Enviar a números de teléfono

Agregar datos personalizados

Ejemplo: Código de Un Solo Uso (OTP)

Solución de problemas

Recursos adicionales