Стартовый набор для телекома: данные и сегменты подписчиков

Это руководство поможет настроить профиль абонента телеком-оператора в Pushwoosh и превратить его в рабочие сегменты: напоминания об истечении срока действия пакета, оповещения о низком балансе, подтверждения пополнения счета и приветственные сообщения в роуминге. Выполните все шаги, и первый же созданный вами сегмент вернет ненулевую аудиторию, так что вам не придется обращаться в службу поддержки.

Самая распространенная ошибка — это тип тега. Дата, сохраненная в теге типа Integer, выглядит нормально в списке тегов, но при этом молча заставляет каждый сегмент по дате возвращать ноль пользователей. Сначала выберите типы, а затем загружайте данные.

Предварительные требования

Приложение в вашем аккаунте Pushwoosh с интегрированным SDK или устройствами, зарегистрированными через API.
Токен доступа к API с разрешением на установку тегов.
Помощь разработчика для настройки задания по обновлению данных между серверами.
Идентификатор абонента, который вы можете сопоставить с Pushwoosh: либо User ID (обычно это MSISDN, номер телефона абонента в международном формате, или внутренний идентификатор абонента), либо HWID устройства.

Как выглядит профиль абонента телеком-оператора

В таблице ниже перечислены теги, которые охватывают стандартные сценарии для телекома. Создайте их перед первой загрузкой данных, используя именно эти типы.

Тег	Тип	Пример значения	Для чего используется
`msisdn`	String	`923001234567`	Идентификация и таргетинг по SMS
`tariff_plan`	String	`Gold Postpaid`	Предложения для конкретных тарифных планов
`prepaid_postpaid`	String	`prepaid`	Разделение базы по модели биллинга
`balance`	Integer	`50`	Оповещения о низком балансе
`bundle_id`	String	`DATA_5GB_30D`	О каком пакете идет речь в напоминании
`bundle_expiry_date`	Date	`2026-09-20 21:00:00`	Напоминания об истечении срока действия пакета
`roaming_status`	Boolean	`true`	Приветственные сообщения в роуминге и предупреждения о расходах в роуминге

Две строки в этой таблице определяют, будут ли сценарии работать вообще.

bundle_expiry_date должен быть тегом типа Date. Только теги типа Date поддерживают относительные операторы, такие как через N — M дней, которые выражают “срок действия пакета истекает через три дня” без необходимости пересчитывать сегмент каждую ночь.
bundle_id хранится отдельно от даты истечения срока. Один тег содержит дату, другой — к какому пакету она относится. Хранение обоих значений в одном теге потребовало бы разбора строки внутри сегмента, что конструктор сегментов делать не умеет.

Почему тип тега определяется до первой загрузки

Теги создаются автоматически при первом поступлении значения, и тип определяется на основе этого первого значения. Целое число становится Integer, число с десятичной точкой — Price, строка — String (или Date, если она соответствует распознаваемому формату даты-времени, например 2024-10-02 22:11), массив — List, а true/false — Boolean.

Для данных телекома такое определение типа не работает, потому что даты истечения срока обычно отправляются в виде Unix-меток времени:

Вы отправляете bundle_expiry_date как число 1758393600. Это целое число, поэтому тег создается как Integer. Значения загружаются корректно, тег выглядит рабочим, но операторы для работы с датами для него никогда не предлагаются.
Тег уже существует как Integer, и позже вы переключаетесь на отправку "2026-09-20". Значение больше не может быть разобрано как число, поэтому оно отбрасывается без какой-либо ошибки. API все равно отвечает успехом, а устройство сохраняет старое значение или не имеет его вовсе.

Оба случая заканчиваются сегментом, который возвращает ноль пользователей, и нигде нет ошибки, которая бы это объяснила.

Тип тега нельзя изменить после создания. Чтобы исправить неверный тип, нужно создать новый тег с правильным типом и перезагрузить в него значения. Старый тег останется в списке, пока вы его не удалите.

Чтобы предотвратить оба случая, установите типы самостоятельно:

Откройте страницу Tags в вашей Панели управления.
Нажмите Создать тег.
Введите имя тега и выберите его тип из списка. Повторите для каждого тега из таблицы выше перед первой загрузкой.
В bulkSetTags отправляйте create_missing_tags: false. В этом случае отсутствующий тег вернет ошибку вместо того, чтобы быть созданным с предполагаемым типом.

Как обновлять профиль между серверами

Данные профиля в телекоме меняются ежедневно, поэтому они загружаются пакетным заданием, а не из мобильного SDK.

Сформируйте на своей стороне ежедневные изменения: абоненты, у которых изменился баланс, пакет или статус роуминга с момента последнего запуска. Полная перезагрузка базы каждую ночь редко бывает нужна и расходует ваш объем запросов.
Отправьте пакет в bulkSetTags, обращаясь к устройствам по user_id, если MSISDN является вашим User ID, или по hwid в противном случае. Один запрос может содержать много устройств, и метод ожидает не менее 50. Для одного абонента используйте setTags.
Опрашивайте возвращенный request_id с помощью bulkSetTags status, пока задание не завершится. Запрашивайте его с ?detailed=true и логируйте результат, потому что завершенное задание не означает, что все значения были приняты.
Повторяйте неудачные пакеты с той же полезной нагрузкой. Установка тега идемпотентна: отправка одного и того же значения дважды оставляет тот же профиль.

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

Какие форматы даты принимает тег типа Date

Тег типа Date хранит Unix-метку времени (epoch timestamp) в секундах. Отправляйте одно из следующих значений:

Значение эпохи в секундах, как число: 1758393600.
Строка даты-времени с разделителями: 2026-09-20 21:00:00, 2026-09-20 21:00 или 2026-09-20. Дата без времени означает полночь.
Строка в формате ISO 8601 со смещением: 2026-09-20T21:00:00+05:00.

Два формата ведут себя так, что это удивляет большинство интеграций:

Строка без часового пояса читается как UTC. Она не читается в вашем локальном времени. Пакет, который истекает в 21:00 в Карачи, это 2026-09-20T21:00:00+05:00 или соответствующее значение эпохи. 2026-09-20 21:00:00 — это на три часа раньше в реальном времени, что перемещает абонентов между волнами ежедневных напоминаний.
Строка из цифр — это значение эпохи, а не дата. "20260920" — это не 20 сентября 2026 года, это метка времени эпохи, указывающая на 1970 год. Отправляйте либо реальное значение эпохи, либо строку с разделителями.

Значение, которое не соответствует ни одному из принятых форматов, отбрасывается без сбоя запроса. Вот почему на шаге 3 выше проверяется результат задания, а не только статус HTTP.

Рецепты сегментов

Каждый рецепт ниже — это один сегмент. Откройте раздел Segments, нажмите Создать сегмент, чтобы открыть конструктор, а затем добавьте перечисленные фильтры. Полное руководство по конструктору см. в Создание сегментов по тегам.

Срок действия пакета истекает через три дня

Таргетирует абонентов, чей текущий пакет заканчивается через три дня, чтобы напоминание пришло, пока продление еще имеет смысл.

Тег: bundle_expiry_date
Оператор: откройте список операторов, перейдите в раздел ОТНОСИТЕЛЬНЫЕ ДАТЫ и выберите через N — M дней
Значения: 3 и 3

Измените оба значения на 1 и 1 для напоминания в последний день. Добавьте второй фильтр по bundle_id, если в сообщении упоминается конкретный пакет.

Низкий баланс

Таргетирует абонентов с предоплатой, которые больше не могут оплатить следующее продление.

Тег: balance, оператор меньше или равно, значение 50
Тег: prepaid_postpaid, оператор равно, значение prepaid

Оба условия помещаются в одну группу, объединенные оператором И.

Вход в роуминг

Таргетирует абонентов, которые в данный момент находятся за границей, для отправки приветственного сообщения с местными тарифами.

Тег: roaming_status, оператор да

Сегмент на основе тегов отражает состояние на момент компиляции. Если вам нужно, чтобы сообщение уходило в момент начала роуминга, запускайте customer journey по событию роуминга, а не отправляйте на этот сегмент.

Подтверждение пополнения и другие реакции

Подтверждение пополнения — это реакция на действие одного абонента, а не аудитория для компиляции. Отправляйте пользовательское событие из вашей биллинговой системы с помощью postEvent и запускайте по нему customer journey. То же самое относится к покупке пакета и смене тарифного плана.

Сегмент возвращает ноль пользователей

Проверьте эти пункты по порядку. Первые три охватывают большинство случаев, о которых сообщают в службу поддержки.

Проверьте тип тега на странице Tags. Если bundle_expiry_date имеет тип Integer, ни один оператор для дат не был применен, и сегмент сравнивал числа. Создайте тег типа Date и перезагрузите значения.
Убедитесь, что значения действительно поступили. Откройте User Explorer, найдите абонента, который, как вы знаете, был в пакете, и посмотрите его теги. Пустой тег после успешного задания означает, что значения были отклонены из-за формата, чаще всего это строки только из цифр или дата, которая не подошла ни под один шаблон.
Проверьте раздел операторов. через N дней в разделе ГОДОВЩИНА игнорирует год. через N — M дней в разделе ОТНОСИТЕЛЬНЫЕ ДАТЫ — нет.
Проверьте часовой пояс. Метки времени истечения срока, отправленные без смещения, читаются как UTC, что может сдвинуть абонента на предыдущий или следующий день вашего расписания напоминаний.
Пересчитайте сегмент перед тем, как смотреть на число, чтобы не видеть кэшированный размер. См. Расчет размера сегмента.

Ограничения, которые следует учитывать

Тип тега является постоянным. Спланируйте профиль перед первой загрузкой, потому что исправление типа позже означает создание нового тега и полную перезагрузку.
Операторы относительных дат недоступны в сегментах для высокоскоростной доставки. Приложения, настроенные для высокоскоростной доставки, предварительно компилируют свои сегменты, и операторы относительных дат там не предлагаются. Напоминания об истечении срока действия пакета должны работать как обычные сегменты.
Пакетное задание не работает в реальном времени. Сегменты видят профиль на момент последней успешной загрузки. Сценарии, которые должны срабатывать в течение нескольких секунд после изменения баланса, должны быть реализованы в journey, запускаемом по событию, а не в ночном пакетном задании.