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	Срок действия фильтра. Фильтр будет автоматически удален в указанную дату, если он не используется в пресете или 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"` добавляет столбцы `Latitude` и `Longitude` в экспортируемый CSV-файл. Если `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 Successful

{
  "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-файл (в зависимости от “format”, указанного в вашем запросе), содержащий данные устройств.

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

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

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

Поле	Описание	Пример значения
Hwid	Аппаратный ID устройства	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