API для сегментации (фильтров)

createFilter

POST https://api.pushwoosh.com/json/1.3/createFilter

Создает новый фильтр.

Тело запроса

Имя	Обязательный	Тип	Описание
auth*	Да	string	Токен доступа к API из Панели управления Pushwoosh.
name*	Да	string	Название фильтра.
filter_expression*	Да	string	Выражение, составленное в соответствии с правилами языка сегментации. Пример: `T(“City”, eq, “Madrid”)` для сегментации пользователей, город которых — Мадрид.
application	Нет	string	Код приложения Pushwoosh. Этот параметр используется только с High-Speed Setup; в противном случае его следует опустить.
expiration_date	Нет	string	Срок действия фильтра. Фильтр будет автоматически удален в указанную дату, если он не используется в пресете (Preset) или RSS-ленте.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "name": "filter name"
  }
}

Пример

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "name": "City = Madrid",
    "filter_expression": "T(\"City\", eq, \"Madrid\")",
    "application": "B18XX-XXXXX",
    "expiration_date": "2025-01-01"
  }
}

// создание фильтров для часовых поясов
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // Токен доступа к API из Панели управления Pushwoosh
    "name": "Timezone Filter",
    "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])"
  }
}

listFilters

POST https://api.pushwoosh.com/json/1.3/listFilters

Возвращает список доступных сегментов (фильтров) с их условиями.

Тело запроса

Имя	Обязательный	Тип	Описание
auth*	Да	string	Токен доступа к API из Панели управления Pushwoosh.
application*	Да	string	Код приложения Pushwoosh

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "filters": [{
      "code": "52551-F2F42",
      "name": "City = Madrid",
      "filter_expression": "T(\"City\", eq, \"madrid\")",
      "expiration_date": "2025-01-01",
      "application": "B18XX-XXXXX"
    }]
  }
}

Пример

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "application": "B18XX-XXXXX"
  }
}

deleteFilter

POST https://api.pushwoosh.com/json/1.3/deleteFilter

Удаляет существующий фильтр.

Тело запроса

Имя	Тип	Описание
auth*	string	Токен доступа к API из Панели управления Pushwoosh.
name*	string	Название фильтра.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // Токен доступа к API из Панели управления Pushwoosh
    "name": "filter name"
  }
}

exportSegment

POST https://api.pushwoosh.com/api/v2/audience/exportSegment

Запланированный запрос. Экспортирует список подписчиков, которые соответствуют указанным условиям фильтра.

Тело запроса

Имя	Обязательный	Тип	Описание
auth*	Да	string	Токен доступа к API из Панели управления Pushwoosh.
filterExpression*	Да	string	Условия фильтрации
exportData	Нет	array	Данные для экспорта. Возможные значения: `"hwids"`, `"push_tokens"`, `"users"`, `"tags"`, `"location"`. Включение `"location"` добавляет в экспортируемый CSV-файл столбцы `Latitude` и `Longitude`. Если `exportData` опущен, `Latitude` и `Longitude` включаются в экспорт по умолчанию.
filterCode	Нет	string	Код готового фильтра, может использоваться вместо filterExpression. Его можно получить из API /listFilters или из адресной строки браузера при просмотре фильтра в Панели управления.
applicationCode	Обязателен, если вы используете `filterExpression` или `filterCode`.	string	Код приложения Pushwoosh.
generateExport	Нет	boolean	По умолчанию установлено значение `true`, и ответ содержит ссылку для скачивания файла. Если `false`, в ответе будет отправлено только количество устройств.
format	Нет	string	Устанавливает формат экспортируемого файла: “csv” или “json_each_line”. Если параметр опущен, генерируется CSV-файл.
tagsList	Нет	array	Указывает теги для экспорта. Чтобы получить только определенные теги, массив “exportData” должен содержать значение “tags”.
includeWithoutTokens	Нет	boolean	Установите значение `true`, чтобы включить в экспортируемый файл пользователей без push-токенов. По умолчанию — `false`.

200 Успешно

{
  "task_id": "177458"
}

{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // обязательно. Токен доступа к API из Панели управления Pushwoosh
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // условия фильтрации, синтаксис см. в руководстве по языку сегментации
  "filterCode": "12345-67890",                              // код готового фильтра, может использоваться вместо filterExpression
  "applicationCode": "00000-AAAAA",                         // Обязателен, если вы используете filterExpression или filterCode. Код приложения Pushwoosh. Его можно получить из ответа на API-запрос /listFilters или из адресной строки браузера при просмотре фильтра в Панели управления.
  "generateExport": true,                                   // если false, в ответе будет отправлено только количество устройств; по умолчанию ответ содержит ссылку для скачивания CSV-файла
  "format": "json_each_line",                               // формат файла для представления данных: "csv" – скачивается .csv-файл; "json" – JSON-файл со всеми экспортированными устройствами; или "json_each_line" – строка JSON для каждого устройства. Если не указан, по умолчанию используется формат CSV.
  "exportData": ["hwids", "tags"],                          // опционально. Данные для экспорта. Возможные значения: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys"
  "tagsList": ["Name", "Level"],                            // опционально. Указывает теги для экспорта. Чтобы получить только определенные теги, значение "tags" должно быть передано в массиве "exportData" или "exportData" должен быть пустым.
  "includeWithoutTokens": true                              // опционально. Установите значение true, чтобы включить в экспортируемый файл пользователей без push-токенов. По умолчанию — false.
}

Например, чтобы экспортировать всех подписчиков определенного приложения, используйте следующие условия фильтра:

{
  "auth": "yxoPUlwqm…………pIyEX4H",            // Токен доступа к API из Панели управления Pushwoosh
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // Выражение фильтра, ссылающееся на сегмент приложения
  "applicationCode": "AAAAA-BBBBB"           // Обязательный код приложения Pushwoosh
}

Результаты exportSegment

POST https://api.pushwoosh.com/api/v2/audience/exportSegment/result

Получает ссылку на CSV-файл с результатами /exportSegment.

Тело запроса

Имя	Тип	Описание
auth*	String	Токен доступа к API из Панели управления Pushwoosh.
task_id*	String	Идентификатор, полученный в ответе на запрос /exportSegment.

200: OK

{
  "devicesCount": "24735",
  "csvFilename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip",
  "status": "completed"
}

Передайте task_id, полученный в ответе на запрос /exportSegment, в теле запроса /exportSegment/result.

В ответе на запрос /exportSegment/result вы получите параметр “filename”. Перейдите по ссылке, указанной в значении этого параметра, чтобы автоматически скачать ZIP-архив. Распакуйте архив, чтобы получить CSV- или JSON-файл (в зависимости от “формата”, указанного в вашем запросе), содержащий данные устройств.

Начиная с 3 апреля 2025 года для скачивания файла потребуется авторизация:

Если вы скачиваете через браузер, просто войдите в Панель управления Pushwoosh, чтобы получить доступ.
Если вы скачиваете с помощью серверного ПО, включите в ваш запрос следующий заголовок: Authorization: Token YOUR_API_TOKEN

Если вы укажете “exportData” в своем запросе /exportSegment, скачанный файл будет содержать только запрошенные данные. По умолчанию файл содержит следующие данные пользователя:

Поле	Описание	Пример значения
Hwid	Аппаратный идентификатор устройства (HWID)	01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8
User ID	Идентификатор пользователя (User ID), связывающий устройство с конкретным пользователем. Если User ID не назначен, используется HWID.	user8192
Push Token	Уникальный идентификатор, присваиваемый устройству облачными шлюзами обмена сообщениями. Подробнее	eeeb2fd7…0fc3547
Type	Тип платформы (целое число).	1
Type (humanized)	Тип платформы (строка).	iOS
Age	Значение тега по умолчанию Age.	29
ApplicationVersion	Значение тега по умолчанию Application Version.	1.12.0.0
City	Значение тега по умолчанию City.	us, boston
TagName	Значение тега, созданного в вашем аккаунте.	TagValue