Démarrage pour les télécoms : données d'abonnés et segments

Ce guide explique comment configurer un profil d’abonné télécom dans Pushwoosh et le transformer en segments fonctionnels : rappels d’expiration de forfait, alertes de solde faible, confirmations de recharge et messages de bienvenue en itinérance. Complétez chaque section et le premier segment que vous créerez renverra une audience non nulle, vous n’aurez donc pas à contacter le support.

L’erreur la plus courante est le type de tag. Une date stockée dans un tag de type Entier (Integer) semble correcte dans la liste des tags, mais fait silencieusement en sorte que chaque segment basé sur la date renvoie zéro utilisateur. Choisissez d’abord les types, puis chargez les données.

Prérequis

Une application dans votre compte Pushwoosh, avec le SDK intégré ou des appareils enregistrés via l’API.
Un jeton d’accès API avec la permission de définir des tags.
L’aide d’un développeur pour la tâche de mise à jour de serveur à serveur.
Un identifiant d’abonné que vous pouvez mapper à Pushwoosh : soit un ID utilisateur (généralement le MSISDN, le numéro de téléphone de l’abonné au format international, ou un ID d’abonné interne) soit l’HWID de l’appareil.

À quoi ressemble un profil d’abonné télécom

Le tableau ci-dessous répertorie les tags qui couvrent les scénarios de télécommunication standard. Créez-les avant le premier chargement de données, avec exactement ces types.

Tag	Type	Exemple de valeur	Ce qu’il pilote
`msisdn`	String	`923001234567`	Identité et ciblage SMS
`tariff_plan`	String	`Gold Postpaid`	Offres spécifiques au forfait
`prepaid_postpaid`	String	`prepaid`	Division de la base par modèle de facturation
`balance`	Integer	`50`	Alertes de solde faible
`bundle_id`	String	`DATA_5GB_30D`	De quel forfait il s’agit pour le rappel
`bundle_expiry_date`	Date	`2026-09-20 21:00:00`	Rappels d’expiration de forfait
`roaming_status`	Boolean	`true`	Messages de bienvenue en itinérance et avertissements sur les frais d’itinérance

Deux lignes de ce tableau sont décisives pour le bon fonctionnement des scénarios.

bundle_expiry_date doit être un tag de type Date. Seuls les tags de type Date disposent des opérateurs relatifs, tels que entre N et M jours à venir, qui expriment « le forfait expire dans trois jours » sans avoir à recalculer le segment chaque nuit.
bundle_id reste séparé de la date d’expiration. Un tag contient la date, un autre contient le forfait auquel elle appartient. Stocker les deux dans un seul tag nécessiterait d’analyser une chaîne de caractères à l’intérieur du segment, ce que le constructeur de segments ne peut pas faire.

Pourquoi le type de tag est décidé avant le premier téléversement

Les tags sont créés automatiquement la première fois qu’une valeur arrive, et le type est déduit de cette première valeur. Un nombre entier devient Entier (Integer), un nombre avec une virgule décimale devient Prix (Price), une chaîne de caractères devient Chaîne (String) (ou Date, si elle correspond à un format de date et d’heure reconnu tel que 2024-10-02 22:11), un tableau devient Liste (List), et true/false devient Booléen (Boolean).

L’inférence échoue sur les données de télécommunication, car les dates d’expiration sont généralement envoyées sous forme d’horodatages Unix :

Vous envoyez bundle_expiry_date sous la forme du nombre 1758393600. C’est un nombre entier, donc le tag est créé en tant que tag Entier (Integer). Les valeurs se chargent correctement, le tag semble sain, et aucun opérateur de date n’est jamais proposé pour lui.
Le tag existe déjà en tant qu’Entier (Integer) et vous passez plus tard à l’envoi de "2026-09-20". La valeur n’est plus analysée comme un nombre, elle est donc abandonnée sans aucune erreur. L’API répond toujours avec succès, et l’appareil conserve son ancienne valeur ou aucune.

Les deux cas se terminent par un segment qui renvoie zéro utilisateur et aucune erreur nulle part pour l’expliquer.

Un type de tag ne peut pas être modifié après sa création. Pour corriger un type erroné, il faut créer un nouveau tag avec le type correct et y recharger les valeurs. L’ancien tag reste dans la liste jusqu’à ce que vous le supprimiez.

Pour éviter ces deux cas, définissez vous-même les types :

Ouvrez la page Tags de votre Panneau de configuration.
Cliquez sur Créer un tag.
Saisissez le nom du tag et choisissez son type dans la liste. Répétez l’opération pour chaque tag du tableau ci-dessus, avant le premier téléversement.
Dans bulkSetTags, envoyez create_missing_tags: false. Un tag manquant renverra alors une erreur au lieu d’être créé avec un type deviné.

Comment mettre à jour le profil de serveur à serveur

Les données de profil des télécoms changent quotidiennement, elles sont donc chargées via une tâche par lots plutôt que depuis le SDK mobile.

Construisez le delta quotidien de votre côté : les abonnés dont le solde, le forfait ou le statut d’itinérance a changé depuis la dernière exécution. Un rechargement complet de la base chaque nuit est rarement nécessaire et vous coûte en volume de requêtes.
Envoyez le lot à bulkSetTags, en adressant les appareils par user_id lorsque le MSISDN est votre ID utilisateur, ou par hwid sinon. Une requête transporte de nombreux appareils, et la méthode en attend au moins 50. Pour un seul abonné, utilisez plutôt setTags.
Interrogez le request_id retourné avec le statut bulkSetTags jusqu’à la fin de la tâche. Demandez-le avec ?detailed=true et enregistrez le résultat, car une tâche terminée ne signifie pas que chaque valeur a été acceptée.
Réessayez les lots échoués avec la même charge utile. La définition d’un tag est idempotente : envoyer deux fois la même valeur laisse le même profil.

{
  "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
    }
  }]
}

Quels formats de date un tag de type Date accepte-t-il

Un tag de type Date stocke un horodatage d’époque Unix en secondes. Envoyez l’un de ces formats :

Une valeur d’époque en secondes, sous forme de nombre : 1758393600.
Une chaîne de date et d’heure avec des séparateurs : 2026-09-20 21:00:00, 2026-09-20 21:00, ou 2026-09-20. Une date sans heure signifie minuit.
Une chaîne ISO 8601 avec un décalage : 2026-09-20T21:00:00+05:00.

Deux formats se comportent d’une manière qui surprend la plupart des intégrations :

Une chaîne sans fuseau horaire est lue comme UTC. Elle n’est pas lue dans votre heure locale. Un forfait qui expire à 21:00 à Karachi est 2026-09-20T21:00:00+05:00, ou la valeur d’époque correspondante. 2026-09-20 21:00:00 est trois heures plus tôt en temps réel, ce qui déplace les abonnés entre les vagues de rappels quotidiens.
Une chaîne de chiffres est une valeur d’époque, pas une date. "20260920" n’est pas le 20 septembre 2026, c’est un horodatage d’époque pointant vers 1970. Envoyez soit une vraie valeur d’époque, soit une chaîne avec des séparateurs.

Une valeur qui ne correspond à aucun des formats acceptés est rejetée sans faire échouer la requête. C’est pourquoi l’étape 3 ci-dessus vérifie le résultat de la tâche plutôt que le seul statut HTTP.

Recettes de segments

Chaque recette ci-dessous correspond à un segment. Ouvrez la section Segments, cliquez sur Créer un segment pour ouvrir le constructeur, puis ajoutez les filtres listés. Pour une présentation complète du constructeur, consultez Créer des segments par tags.

Le forfait expire dans trois jours

Cible les abonnés dont le forfait actuel se termine dans trois jours, afin que le rappel arrive à un moment où un renouvellement a encore du sens.

Tag : bundle_expiry_date
Opérateur : ouvrez la liste des opérateurs, allez à la section DATES RELATIVES, et choisissez entre N et M jours à venir
Valeurs : 3 et 3

Changez les deux valeurs à 1 et 1 pour le rappel du dernier jour. Ajoutez un deuxième filtre sur bundle_id lorsque le message nomme le forfait spécifique.

Solde faible

Cible les abonnés prépayés qui ne peuvent plus payer pour le prochain renouvellement.

Tag : balance, opérateur inférieur ou égal à, valeur 50
Tag : prepaid_postpaid, opérateur égal à, valeur prepaid

Les deux conditions vont dans le même groupe, combinées avec ET.

Entrée en itinérance

Cible les abonnés qui sont actuellement à l’étranger, pour un message de bienvenue avec les tarifs locaux.

Tag : roaming_status, opérateur vrai

Un segment basé sur les tags reflète l’état au moment de la compilation. Lorsque vous avez besoin que le message soit envoyé au moment même où l’itinérance commence, déclenchez un parcours client à partir d’un événement d’itinérance au lieu d’envoyer à ce segment.

Confirmation de recharge et autres réactions

Confirmer une recharge est une réaction à l’action d’un seul abonné, pas une audience à compiler. Envoyez un événement personnalisé depuis votre système de facturation avec postEvent et démarrez un parcours client à partir de celui-ci. Il en va de même pour l’achat d’un forfait et le changement de plan.

Le segment renvoie zéro utilisateur

Vérifiez ces points dans l’ordre. Les trois premiers couvrent la plupart des cas signalés au support.

Vérifiez le type de tag sur la page Tags. Si bundle_expiry_date est de type Entier (Integer), aucun opérateur de date n’a jamais été appliqué et le segment a comparé des nombres. Créez un tag de type Date et rechargez les valeurs.
Vérifiez que les valeurs sont bien arrivées. Ouvrez l’Explorateur d’utilisateurs, trouvez un abonné que vous savez être dans le lot, et regardez ses tags. Un tag vide après une tâche réussie signifie que les valeurs ont été rejetées en raison de leur format, le plus souvent des chaînes de chiffres uniquement ou une date qui ne correspondait à aucun format.
Vérifiez la section de l’opérateur. est dans N jours sous ANNIVERSAIRE ignore l’année. entre N et M jours à venir sous DATES RELATIVES ne l’ignore pas.
Vérifiez le fuseau horaire. Les horodatages d’expiration envoyés sans décalage sont lus comme UTC, ce qui peut décaler un abonné vers le jour précédent ou suivant de votre calendrier de rappels.
Recalculez le segment avant de lire le nombre, afin de ne pas regarder une taille mise en cache. Voir Calcul de la taille du segment.

Limitations à prendre en compte

Un type de tag est permanent. Planifiez le profil avant le premier téléversement, car corriger un type plus tard signifie un nouveau tag et un rechargement complet.
Les opérateurs de date relative ne sont pas disponibles dans les segments de livraison à haute vitesse. Les applications configurées pour la livraison à haute vitesse précompilent leurs segments, et les opérateurs de date relative n’y sont pas proposés. Les rappels d’expiration de forfait doivent être exécutés en tant que segments ordinaires.
Une tâche par lots n’est pas en temps réel. Les segments voient le profil tel qu’il était lors du dernier chargement réussi. Les scénarios qui doivent se déclencher quelques secondes après un changement de solde appartiennent à un parcours déclenché par un événement, pas à un lot nocturne.