Guía de inicio para telecomunicaciones: datos y segmentos de suscriptores

Esta guía configura un perfil de suscriptor de telecomunicaciones en Pushwoosh y lo convierte en segmentos funcionales: recordatorios de vencimiento de paquetes, alertas de saldo bajo, confirmaciones de recarga y mensajes de bienvenida en roaming. Complete todas las secciones y el primer segmento que cree devolverá una audiencia distinta de cero, para que no tenga que ponerse en contacto con el soporte.

El error más común es el tipo de etiqueta. Una fecha almacenada en una etiqueta de tipo Integer se ve bien en la lista de etiquetas y silenciosamente hace que cada segmento de fecha devuelva cero usuarios. Elija primero los tipos y luego cargue los datos.

Requisitos previos

• Una aplicación en su cuenta de Pushwoosh, con el SDK integrado o dispositivos registrados a través de la API.
• Un token de acceso a la API con permiso para establecer etiquetas.
• Asistencia de un desarrollador para el trabajo de actualización de servidor a servidor.
• Un identificador de suscriptor que pueda asignar a Pushwoosh: ya sea un User ID (generalmente el MSISDN, el número de teléfono del suscriptor en formato internacional, o un ID de suscriptor interno) o el HWID del dispositivo.

Cómo es un perfil de suscriptor de telecomunicaciones

La siguiente tabla enumera las etiquetas que cubren los escenarios estándar de telecomunicaciones. Créelas antes de la primera carga de datos, con exactamente estos tipos.

Etiqueta	Tipo	Valor de ejemplo	Para qué sirve
msisdn	String	923001234567	Identidad y segmentación por SMS
tariff_plan	String	Gold Postpaid	Ofertas específicas del plan
prepaid_postpaid	String	prepaid	Dividir la base por modelo de facturación
balance	Integer	50	Alertas de saldo bajo
bundle_id	String	DATA_5GB_30D	Sobre qué paquete es el recordatorio
bundle_expiry_date	Date	2026-09-20 21:00:00	Recordatorios de vencimiento de paquetes
roaming_status	Boolean	true	Mensajes de bienvenida en roaming y advertencias sobre cargos de roaming

Dos filas en esa tabla deciden si los escenarios funcionan o no.

• bundle_expiry_date tiene que ser una etiqueta de tipo Date. Solo las etiquetas de tipo Date tienen los operadores relativos, como entre N y M días a partir de hoy, que expresan “el paquete vence en tres días” sin tener que recalcular el segmento cada noche.
• bundle_id se mantiene separado de la fecha de vencimiento. Una etiqueta contiene la fecha, otra contiene a qué paquete pertenece. Almacenar ambos en una sola etiqueta requeriría analizar una cadena de texto dentro del segmento, lo cual el creador de segmentos no puede hacer.

Por qué el tipo de etiqueta se decide antes de la primera carga

Las etiquetas se crean automáticamente la primera vez que llega un valor, y el tipo se infiere de ese primer valor. Un número entero se convierte en Integer, un número con un punto decimal se convierte en Price, una cadena de texto se convierte en String (o Date, si coincide con un formato de fecha y hora reconocido como 2024-10-02 22:11), un array se convierte en List, y true/false se convierte en Boolean.

La inferencia falla con los datos de telecomunicaciones, porque las fechas de vencimiento generalmente se envían como marcas de tiempo Unix (Unix timestamps):

• Usted envía bundle_expiry_date como el número 1758393600. Es un número entero, por lo que la etiqueta se crea como una etiqueta de tipo Integer. Los valores se cargan correctamente, la etiqueta parece estar bien y nunca se ofrece un operador de fecha para ella.
• La etiqueta ya existe como Integer y más tarde cambia a enviar "2026-09-20". El valor ya no se analiza como un número, por lo que se descarta sin ningún error. La API sigue respondiendo con éxito y el dispositivo mantiene su valor anterior o ninguno.

Ambos casos terminan con un segmento que devuelve cero usuarios y ningún error en ninguna parte que lo explique.

El tipo de una etiqueta no se puede cambiar después de su creación. Arreglar un tipo incorrecto significa crear una nueva etiqueta con el tipo correcto y volver a cargar los valores en ella. La etiqueta antigua permanece en la lista hasta que la elimine.

Para evitar ambos casos, establezca los tipos usted mismo:

1. Abra la página de Etiquetas de su Panel de Control.
2. Haga clic en Crear etiqueta.
3. Ingrese el nombre de la etiqueta y elija su tipo de la lista. Repita para cada etiqueta de la tabla anterior, antes de la primera carga.
4. En bulkSetTags, envíe create_missing_tags: false. Una etiqueta faltante devolverá un error en lugar de ser creada con un tipo adivinado.

Cómo actualizar el perfil de servidor a servidor

Los datos del perfil de telecomunicaciones cambian a diario, por lo que se cargan como un trabajo por lotes en lugar de desde el SDK móvil.

1. Cree el delta diario de su lado: suscriptores cuyo saldo, paquete o estado de roaming ha cambiado desde la última ejecución. Una recarga completa de la base cada noche rara vez es necesaria y le cuesta volumen de solicitudes.
2. Envíe el lote a bulkSetTags, dirigiéndose a los dispositivos por user_id cuando el MSISDN es su User ID, o por hwid en caso contrario. Una solicitud transporta muchos dispositivos, y el método espera al menos 50 de ellos. Para un solo suscriptor, use setTags en su lugar.
3. Sondee el request_id devuelto con el estado de bulkSetTags hasta que el trabajo finalice. Solicítelo con ?detailed=true y registre el resultado, porque un trabajo finalizado no es lo mismo que cada valor haya sido aceptado.
4. Reintente los lotes fallidos con la misma carga útil. Establecer una etiqueta es idempotente: enviar el mismo valor dos veces deja el mismo perfil.

Actualización diaria de paquetes

{
  "application": "XXXXX-XXXXX",
  "auth": "your API access token",
  "create_missing_tags": false,
  "devices": [{
    "user_id": "923001234567",
    "tags": {
      "bundle_id": "DATA_5GB_30D",
      "bundle_expiry_date": "2026-09-20 21:00:00",
      "balance": 50,
      "roaming_status": false
    }
  }]
}

Qué formatos de fecha acepta una etiqueta de tipo Date

Una etiqueta de tipo Date almacena una marca de tiempo de la época Unix (epoch timestamp) en segundos. Envíe uno de estos:

• Un valor de época en segundos, como un número: 1758393600.
• Una cadena de fecha y hora con separadores: 2026-09-20 21:00:00, 2026-09-20 21:00, o 2026-09-20. Una fecha sin hora significa medianoche.
• Una cadena ISO 8601 con un desfase horario: 2026-09-20T21:00:00+05:00.

Dos formatos se comportan de una manera que sorprende a la mayoría de las integraciones:

• Una cadena de texto sin zona horaria se lee como UTC. No se lee en su hora local. Un paquete que vence a las 21:00 en Karachi es 2026-09-20T21:00:00+05:00, o el valor de época correspondiente. 2026-09-20 21:00:00 es tres horas antes en tiempo real, lo que mueve a los suscriptores entre las oleadas de recordatorios diarios.
• Una cadena de dígitos es un valor de época, no una fecha. "20260920" no es el 20 de septiembre de 2026, es una marca de tiempo de época que apunta a 1970. Envíe un valor de época real o una cadena de texto con separadores.

Un valor que no coincide con ninguno de los formatos aceptados se descarta sin que la solicitud falle. Es por eso que el paso 3 anterior verifica el resultado del trabajo en lugar de solo el estado HTTP.

Recetas de segmentos

Cada receta a continuación es un segmento. Abra la sección de Segmentos, haga clic en Crear segmento para abrir el creador, y luego agregue los filtros listados. Para ver el tutorial completo del creador, consulte Crear segmentos por etiquetas.

El paquete vence en tres días

Se dirige a los suscriptores cuyo paquete actual se agota en tres días, para que el recordatorio llegue cuando una renovación todavía tiene sentido.

• Etiqueta: bundle_expiry_date
• Operador: abra la lista de operadores, vaya a la sección FECHAS RELATIVAS y elija entre N y M días a partir de hoy
• Valores: 3 y 3

Cambie ambos valores a 1 y 1 para el recordatorio del último día. Agregue un segundo filtro en bundle_id cuando el mensaje mencione el paquete específico.

No utilice aquí los operadores de la sección ANIVERSARIO

La sección ANIVERSARIO ofrece es dentro de N días. Ese operador compara solo el día y el mes, por lo que coincide con cada suscriptor cuyo paquete expiró en esa fecha en cualquier año. Úselo para cumpleaños, no para la validez de un paquete.

Saldo bajo

Se dirige a los suscriptores de prepago que ya no pueden pagar la próxima renovación.

• Etiqueta: balance, operador menor o igual que, valor 50
• Etiqueta: prepaid_postpaid, operador igual a, valor prepaid

Ambas condiciones van en el mismo grupo, combinadas con Y.

Entrada en roaming

Se dirige a los suscriptores que se encuentran actualmente en el extranjero, para un mensaje de bienvenida con las tarifas locales.

• Etiqueta: roaming_status, operador verdadero

Un segmento basado en etiquetas refleja el estado en el momento de la compilación. Cuando necesite que el mensaje se envíe en el momento en que comienza el roaming, active un customer journey desde un evento de roaming en lugar de enviar a este segmento.

Confirmación de recarga y otras reacciones

Confirmar una recarga es una reacción a la acción de un solo suscriptor, no una audiencia para compilar. Envíe un evento personalizado desde su sistema de facturación con postEvent e inicie un customer journey a partir de él. Lo mismo se aplica a la compra de paquetes y al cambio de plan.

El segmento devuelve cero usuarios

Verifique esto en orden. Los tres primeros cubren la mayoría de los casos reportados a soporte.

1. Verifique el tipo de etiqueta en la página de Etiquetas. Si bundle_expiry_date es Integer, nunca se aplicó un operador de fecha y el segmento comparó números. Cree una etiqueta de tipo Date y vuelva a cargar los valores.
2. Verifique que los valores realmente llegaron. Abra el User Explorer, encuentre un suscriptor que sepa que estaba en el lote y mire sus etiquetas. Una etiqueta vacía después de un trabajo exitoso significa que los valores fueron rechazados por el formato, la mayoría de las veces cadenas de solo dígitos o una fecha que no coincidía con ningún diseño.
3. Verifique la sección del operador. es dentro de N días en ANIVERSARIO ignora el año. entre N y M días a partir de hoy en FECHAS RELATIVAS no lo hace.
4. Verifique la zona horaria. Las marcas de tiempo de vencimiento enviadas sin un desfase horario se leen como UTC, lo que puede cambiar a un suscriptor al día anterior o siguiente de su programa de recordatorios.
5. Recalcule el segmento antes de leer el número, para no estar viendo un tamaño en caché. Consulte Calcular el tamaño del segmento.

Limitaciones a tener en cuenta

• El tipo de una etiqueta es permanente. Planifique el perfil antes de la primera carga, porque arreglar un tipo más tarde significa una nueva etiqueta y una recarga completa.
• Los operadores de fecha relativa no están disponibles en los segmentos de entrega de alta velocidad. Las aplicaciones configuradas para la entrega de alta velocidad precompilan sus segmentos, y los operadores de fecha relativa no se ofrecen allí. Los recordatorios de vencimiento de paquetes deben ejecutarse como segmentos ordinarios.
• Un trabajo por lotes no es en tiempo real. Los segmentos ven el perfil a partir de la última carga exitosa. Los escenarios que deben activarse a los pocos segundos de un cambio de saldo pertenecen a un journey activado por eventos, no a un lote nocturno.