API de segmentación (filtros)

createFilter

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

Crea un nuevo filtro.

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Descripción
auth*	Sí	string	Token de acceso a la API del Panel de Control de Pushwoosh.
name*	Sí	string	Nombre del filtro.
filter_expression*	Sí	string	Expresión construida según las reglas del lenguaje de segmentación. Ejemplo: T(“City”, eq, “Madrid”) para segmentar usuarios cuya ciudad es Madrid.
application	No	string	Código de aplicación de Pushwoosh. Este parámetro solo se puede usar con la configuración de alta velocidad; de lo contrario, omítalo.
expiration_date	No	string	Vencimiento del filtro. El filtro se eliminará automáticamente en la fecha especificada, a menos que se use en un Preset o en una fuente RSS.

200

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

Ejemplo

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

// creating Filters for Timezones
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
    "name": "Timezone Filter",
    "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])"
  }
}

listFilters

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

Devuelve una lista de los segmentos (filtros) disponibles con sus condiciones.

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Descripción
auth*	Sí	string	Token de acceso a la API del Panel de Control de Pushwoosh.
application*	Sí	string	Código de aplicación de 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"
    }]
  }
}

Ejemplo

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

deleteFilter

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

Elimina un filtro existente.

Cuerpo de la solicitud

Nombre	Tipo	Descripción
auth*	string	Token de acceso a la API del Panel de Control de Pushwoosh.
name*	string	Nombre del filtro.

200

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

Ejemplo

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
    "name": "filter name"
  }
}

exportSegment

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

Una solicitud programada. Exporta la lista de suscriptores que cumplen con las condiciones del filtro especificadas.

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Descripción
auth*	Sí	string	Token de acceso a la API del Panel de Control de Pushwoosh.
filterExpression*	Sí	string	Condiciones del filtro
exportData	No	array	Datos a exportar. Valores posibles: "hwids", "push_tokens", "users", "tags", "location", "ad_identifiers". Incluir "location" agrega las columnas Latitude y Longitude al CSV exportado. Si se omite exportData, Latitude y Longitude se incluyen en la exportación por defecto. "ad_identifiers" agrega las columnas MADID, Email SHA256 y Phone SHA256 para construir un archivo fuente de Google Customer Match o Meta Custom Audience — vea la nota de exportación de identificadores de anuncios a continuación.
filterCode	No	string	Código de filtro predefinido, se puede usar en lugar de filterExpression. Se puede obtener de la API /listFilters o de la barra de direcciones de su navegador al ver el filtro en el Panel de Control.
applicationCode	Requerido si está usando filterExpression o filterCode.	string	Código de aplicación de Pushwoosh
generateExport	No	boolean	Por defecto se establece en true, y una respuesta contiene un enlace para descargar el archivo. Si es falso, solo se enviará el recuento de dispositivos en la respuesta.
format	No	string	Establece el formato del archivo exportado: “csv” o “json_each_line”. Si se omite, se genera el archivo CSV.
tagsList	No	array	Especifica las etiquetas a exportar. Para obtener solo las etiquetas específicas, el array “exportData” debe contener el valor “tags”.
includeWithoutTokens	No	boolean	Establezca en true para incluir usuarios sin tokens push en el archivo exportado. El valor predeterminado es false.

200 Exitoso

{
  "task_id": "177458"
}

Ejemplo

{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // required. API access token from Pushwoosh Control Panel
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // filter conditions, refer to the Segmentation Language guide for syntax
  "filterCode": "12345-67890",                              // pre-made filter code, can be used instead of filterExpression
  "applicationCode": "00000-AAAAA",                         // Required if you're using either `filterExpression` or `filterCode`. Pushwoosh app code. Can be obtained from /listFilters API request or address bar of your browser while viewing the filter in Control Panel.
  "generateExport": true,                                   // if false, devices count only will be sent in response; by default, a response contains a link to download the CSV file
  "format": "json_each_line",                               // format of the file to present the data in: "csv" – the .csv file is downloaded; "json" – a JSON file with all expored devices; or "json_each_line" – JSON line for each device. If not specified, CSV is the default format.
  "exportData": ["hwids", "tags"],                          // optional. Data to export. Possible values: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys", "ad_identifiers"
  "tagsList": ["Name", "Level"],                            // optional. Specifies tags to export. To obtain the specific tags only, the "tags" value should be sent within the "exportData" array or the "exportData" be empty.
  "includeWithoutTokens": true                              // optional. Set to true to include users without push tokens in the exported file. Default is false.
}

Nota

Por favor, encuentre la referencia del Lenguaje de Segmentación para escribir expresiones de filtro aquí.

Por ejemplo, para exportar todos los suscriptores de una aplicación en particular, use las siguientes condiciones de filtro:

{
  "auth": "yxoPUlwqm…………pIyEX4H",            // API access token from Pushwoosh Control Panel
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // Filter expression referencing app segment
  "applicationCode": "AAAAA-BBBBB"           // Required Pushwoosh app code
}

Precaución

En la respuesta, obtendrá el task_id para obtener el archivo resultante. Luego, llame a /exportSegment/result con ese task_id en el cuerpo de la solicitud para recuperar el archivo resultante.

exportSegment results

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

Recupera el enlace al CSV con los resultados de /exportSegment.

Cuerpo de la solicitud

Nombre	Tipo	Descripción
auth*	String	Token de acceso a la API del Panel de Control de Pushwoosh.
task_id*	String	Identificador recibido en su respuesta de /exportSegment.

200: OK

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

Pase el “task_id” recibido en su respuesta de /exportSegment en el cuerpo de la solicitud de /exportSegment/result.

En la respuesta de /exportSegment/result, recibirá el parámetro “filename”. Siga el enlace proporcionado en el valor de ese parámetro para descargar automáticamente un archivo ZIP. Descomprima el archivo para recuperar el archivo CSV o JSON (dependiendo del “format” especificado en su solicitud) que contiene los datos de los dispositivos.

A partir del 3 de abril de 2025, se requerirá autorización para descargar el archivo:

• Si descarga a través de un navegador, simplemente inicie sesión en el Panel de Control de Pushwoosh para obtener acceso.
• Si descarga a través de software de servidor, incluya el siguiente encabezado en su solicitud: Authorization: Token YOUR_API_TOKEN

Si especifica el “exportData” en su solicitud de /exportSegment, el archivo descargado contendrá solo los datos solicitados. Por defecto, el archivo contiene los siguientes datos de usuario:

Campo	Descripción	Ejemplo de valor
Hwid	ID de hardware de un dispositivo	01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8
User ID	ID de usuario que asocia un dispositivo con un usuario en particular. Si no se asigna un ID de usuario, se utiliza el HWID.	user8192
Push Token	Identificador único asignado a un dispositivo por las pasarelas de mensajería en la nube. Más información	eeeb2fd7…0fc3547
Type	Tipo de plataforma (entero).	1
Type (humanized)	Tipo de plataforma (cadena).	iOS
Age	Valor de la etiqueta predeterminada Age.	29
ApplicationVersion	Valor de la etiqueta predeterminada Application Version.	1.12.0.0
City	Valor de la etiqueta predeterminada City.	us, boston
TagName	Valor de una etiqueta creada en su cuenta.	TagValue

Exportación de identificadores de anuncios

Agregue "ad_identifiers" a exportData para obtener un archivo formateado para subirlo directamente como fuente de Google Customer Match o Meta Custom Audience. Este valor es solo opcional — nunca se incluye por defecto, incluso cuando se omite exportData. Solo tiene efecto con format establecido en "csv". Solicitarlo con "json" o "json_each_line" no devuelve un error, pero las columnas a continuación se omiten silenciosamente de esos formatos.

Campo	Descripción
MADID	ID de publicidad móvil (GAID o IDFA), normalizado a minúsculas.
Email SHA256	Hash SHA-256 del correo electrónico del usuario, en minúsculas y sin espacios antes de aplicar el hash.
Phone SHA256	Hash SHA-256 del número de teléfono del usuario en formato E.164 antes de aplicar el hash.

Una fila para un usuario sin ninguno de los tres identificadores se exporta de todos modos, con las columnas MADID, Email SHA256 y Phone SHA256 vacías.

Exportar actividad de la aplicación por usuario

Nota

Estadísticas de campaña devuelven recuentos de aperturas/envíos agregados por hora y plataforma. No hay columna hwid o user_id. Para ver qué usuarios abrieron la aplicación y cuándo, exporte un segmento construido sobre el evento PW_ApplicationOpen en su lugar.

PW_ApplicationOpen es solo para móviles. Para un proyecto web, la exportación del segmento no devuelve filas, ya que el evento nunca se activa allí.

1. Construya una expresión de filtro sobre el evento PW_ApplicationOpen, limitado al período que necesite. Use los operadores de fecha de evento, por ejemplo “abierto ayer”:

Event("AAAAA-BBBBB", "PW_ApplicationOpen", date daysago eq 1)

2. Llame a /exportSegment con esa filterExpression, applicationCode y exportData: ["hwids", "users"].
3. Llame a /exportSegment/result con el task_id devuelto para descargar el CSV con las columnas Hwid y User ID para cada dispositivo que abrió la aplicación en esa ventana.

Precaución

User ID contiene cualquier identificador que asigne a un dispositivo. Si no asigna uno, se recurre al HWID. La exportación le dice quién abrió la aplicación dentro de la ventana filtrada. No es un registro de eventos por apertura con una columna de marca de tiempo, así que construya un segmento por día (o ventana) si necesita granularidad día a día.