API de Segmentação (Filtros)

createFilter

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

Cria um novo filtro.

Corpo da solicitação

Nome	Obrigatório	Tipo	Descrição
auth*	Sim	string	Token de acesso à API do Painel de Controle da Pushwoosh.
name*	Sim	string	Nome do filtro.
filter_expression*	Sim	string	Expressão construída de acordo com as regras da linguagem de Segmentação. Exemplo: T(“City”, eq, “Madrid”) para segmentar usuários cuja cidade é Madrid.
application	Não	string	Código do aplicativo Pushwoosh. Este parâmetro é utilizável apenas com a Configuração de Alta Velocidade; omita caso contrário.
expiration_date	Não	string	Expiração do filtro. O filtro será excluído automaticamente na data especificada, a menos que seja usado em uma Predefinição ou em um Feed RSS.

200

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

Exemplo

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

// criando Filtros para Fusos Horários
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // token de acesso à API do Painel de Controle da 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

Retorna uma lista de segmentos (filtros) disponíveis com suas condições.

Corpo da Solicitação

Nome	Obrigatório	Tipo	Descrição
auth*	Sim	string	Token de acesso à API do Painel de Controle da Pushwoosh.
application*	Sim	string	Código do aplicativo 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"
    }]
  }
}

Exemplo

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

deleteFilter

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

Exclui um filtro existente.

Corpo da Solicitação

Nome	Tipo	Descrição
auth*	string	Token de acesso à API do Painel de Controle da Pushwoosh.
name*	string	Nome do filtro.

200

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

Exemplo

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // token de acesso à API do Painel de Controle da Pushwoosh
    "name": "filter name"
  }
}

exportSegment

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

Uma solicitação agendada. Exporta a lista de assinantes que se enquadram nas condições de Filtro especificadas.

Corpo da solicitação

Nome	Obrigatório	Tipo	Descrição
auth*	Sim	string	Token de acesso à API do Painel de Controle da Pushwoosh.
filterExpression*	Sim	string	Condições do filtro
exportData	Não	array	Dados para exportar. Valores possíveis: "hwids", "push_tokens", "users", "tags", "location", "ad_identifiers". Incluir "location" adiciona as colunas Latitude e Longitude ao CSV exportado. Se exportData for omitido, Latitude e Longitude são incluídos na exportação por padrão. "ad_identifiers" adiciona as colunas MADID, Email SHA256 e Phone SHA256 para construir um arquivo de origem do Google Customer Match ou Meta Custom Audience — veja a nota exportação de identificadores de anúncio abaixo.
filterCode	Não	string	Código de filtro pré-fabricado, pode ser usado em vez de filterExpression. Pode ser obtido na API /listFilters ou na barra de endereço do seu navegador ao visualizar o filtro no Painel de Controle.
applicationCode	Obrigatório se você estiver usando filterExpression ou filterCode.	string	Código do aplicativo Pushwoosh
generateExport	Não	boolean	Por padrão, definido como true, e uma resposta contém um link para baixar o arquivo. Se for false, apenas a contagem de dispositivos será enviada na resposta.
format	Não	string	Define o formato do arquivo exportado: “csv” ou “json_each_line”. Se omitido, o arquivo CSV é gerado.
tagsList	Não	array	Especifica as tags a serem exportadas. Para obter apenas as tags específicas, o array “exportData” deve conter o valor “tags”.
includeWithoutTokens	Não	boolean	Defina como true para incluir usuários sem tokens de push no arquivo exportado. O padrão é false.

200 Bem-sucedido

{
  "task_id": "177458"
}

Exemplo

{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // obrigatório. Token de acesso à API do Painel de Controle da Pushwoosh
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // condições do filtro, consulte o guia da Linguagem de Segmentação para a sintaxe
  "filterCode": "12345-67890",                              // código de filtro pré-fabricado, pode ser usado em vez de filterExpression
  "applicationCode": "00000-AAAAA",                         // Obrigatório se você estiver usando `filterExpression` ou `filterCode`. Código do aplicativo Pushwoosh. Pode ser obtido na solicitação da API /listFilters ou na barra de endereço do seu navegador ao visualizar o filtro no Painel de Controle.
  "generateExport": true,                                   // se for false, apenas a contagem de dispositivos será enviada na resposta; por padrão, uma resposta contém um link para baixar o arquivo CSV
  "format": "json_each_line",                               // formato do arquivo para apresentar os dados: "csv" – o arquivo .csv é baixado; "json" – um arquivo JSON com todos os dispositivos exportados; ou "json_each_line" – uma linha JSON para cada dispositivo. Se não especificado, CSV é o formato padrão.
  "exportData": ["hwids", "tags"],                          // opcional. Dados para exportar. Valores possíveis: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys", "ad_identifiers"
  "tagsList": ["Name", "Level"],                            // opcional. Especifica as tags a serem exportadas. Para obter apenas as tags específicas, o valor "tags" deve ser enviado dentro do array "exportData" ou o "exportData" deve estar vazio.
  "includeWithoutTokens": true                              // opcional. Defina como true para incluir usuários sem tokens de push no arquivo exportado. O padrão é false.
}

Nota

Por favor, encontre a referência da Linguagem de Segmentação para escrever expressões de filtro aqui.

Por exemplo, para exportar todos os assinantes de um aplicativo específico, use as seguintes condições de Filtro:

{
  "auth": "yxoPUlwqm…………pIyEX4H",            // Token de acesso à API do Painel de Controle da Pushwoosh
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // Expressão de filtro referenciando o segmento do aplicativo
  "applicationCode": "AAAAA-BBBBB"           // Código do aplicativo Pushwoosh obrigatório
}

Cuidado

Na resposta, você receberá o task_id para obter o arquivo resultante. Em seguida, chame /exportSegment/result com esse task_id no corpo da solicitação para recuperar o arquivo resultante.

resultados de exportSegment

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

Recupera o link para o CSV com os resultados de /exportSegment.

Corpo da Solicitação

Nome	Tipo	Descrição
auth*	String	Token de acesso à API do Painel de Controle da Pushwoosh.
task_id*	String	Identificador recebido na sua resposta /exportSegment.

200: OK

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

Passe o “task_id” recebido na sua resposta /exportSegment no corpo da solicitação /exportSegment/result.

Na resposta /exportSegment/result, você receberá o parâmetro “filename”. Siga o link fornecido no valor desse parâmetro para baixar automaticamente um arquivo ZIP. Descompacte o arquivo para recuperar o arquivo CSV ou JSON (dependendo do “formato” especificado em sua solicitação) contendo os dados dos dispositivos.

A partir de 3 de abril de 2025, a autorização será necessária para baixar o arquivo:

• Se estiver baixando por um navegador, basta fazer login no Painel de Controle da Pushwoosh para obter acesso.
• Se estiver baixando por um software de servidor, inclua o seguinte cabeçalho em sua solicitação: Authorization: Token SEU_TOKEN_DE_API

Se você especificar o “exportData” em sua solicitação /exportSegment, o arquivo baixado conterá apenas os dados solicitados. Por padrão, o arquivo contém os seguintes dados do usuário:

Campo	Descrição	Exemplo de valor
Hwid	ID de Hardware de um dispositivo	01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8
User ID	ID de Usuário associando um dispositivo a um usuário específico. Se nenhum ID de Usuário for atribuído, o HWID é usado.	user8192
Push Token	Identificador único atribuído a um dispositivo por gateways de mensagens na nuvem. Saiba mais	eeeb2fd7…0fc3547
Type	Tipo de plataforma (inteiro).	1
Type (humanized)	Tipo de plataforma (string).	iOS
Age	Valor da tag padrão Idade.	29
ApplicationVersion	Valor da tag padrão Versão do Aplicativo.	1.12.0.0
City	Valor da tag padrão Cidade.	us, boston
TagName	Valor de uma tag criada em sua conta.	TagValue

Exportação de identificadores de anúncio

Adicione "ad_identifiers" a exportData para obter um arquivo formatado para upload direto como uma fonte do Google Customer Match ou Meta Custom Audience. Este valor é opcional — nunca é incluído por padrão, mesmo quando exportData é omitido. Ele só tem efeito com format definido como "csv". Solicitá-lo com "json" ou "json_each_line" não retorna um erro, mas as colunas abaixo são omitidas silenciosamente desses formatos.

Campo	Descrição
MADID	ID de publicidade móvel (GAID ou IDFA), normalizado para minúsculas.
Email SHA256	Hash SHA-256 do e-mail do usuário, em minúsculas e sem espaços antes do hashing.
Phone SHA256	Hash SHA-256 do número de telefone do usuário no formato E.164 antes do hashing.

Uma linha para um usuário sem nenhum dos três identificadores ainda é exportada, com as colunas MADID, Email SHA256 e Phone SHA256 deixadas em branco.

Exportar atividade de aplicativo por usuário

Nota

As estatísticas de campanha retornam contagens de aberturas/envios agregadas por hora e plataforma. Não há coluna hwid ou user_id. Para ver quais usuários abriram o aplicativo e quando, exporte um segmento construído no evento PW_ApplicationOpen.

PW_ApplicationOpen é apenas para dispositivos móveis. Para um projeto web, a exportação de segmento não retorna linhas, pois o evento nunca é disparado lá.

1. Construa uma expressão de filtro no evento PW_ApplicationOpen, com escopo para o período que você precisa. Use os operadores de data do evento, por exemplo, “aberto ontem”:

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

2. Chame /exportSegment com essa filterExpression, applicationCode e exportData: ["hwids", "users"].
3. Chame /exportSegment/result com o task_id retornado para baixar o CSV com as colunas Hwid e User ID para cada dispositivo que abriu o aplicativo nessa janela.

Cuidado

User ID contém qualquer identificador que você atribui a um dispositivo. Se você não atribuir um, ele volta para o HWID. A exportação informa quem abriu o aplicativo dentro da janela filtrada. Não é um log de eventos por abertura com uma coluna de carimbo de data/hora, então construa um segmento por dia (ou janela) se precisar de granularidade diária.