Saltar al contenido principal
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:

​
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"
}

​
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:
  1. Crea un Template vía el dashboard o Create template API.
  2. Agrega Variables Liquid (ej., {{ message.custom_data.order_id }}) a tu plantilla.
  3. 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)

  1. Identifica al usuario usando un alias, email o número de teléfono.
  2. Crea un Template que incluya un código de verificación:
Your verification code is {{ message.custom_data.verification_code }}
  1. Genera el verification_code en tu servidor cuando el usuario solicita acceso.
  2. 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.

​
Recursos adicionales