Exportação assíncrona de estatísticas de mensagens

exportMessagesStatistics exporta o histórico e as estatísticas de mensagens para um arquivo CSV no servidor. Use-o para extrações grandes ou de contas completas que o messages:list não consegue lidar.

Quando usar a exportação em vez de messages:list

Use messages:list para pesquisas ao vivo e paginadas de um período delimitado. Use exportMessagesStatistics quando o resultado exceder o limite de paginação profunda de messages:list (page × per_page > 100000), ou quando o objetivo for um único arquivo para download em vez de JSON paginado. A exportação não tem limite de date_range ou contagem de linhas, porque transmite o resultado para um arquivo em disco em vez de mantê-lo em uma única resposta.

Como funciona o fluxo de exportação

1. Chame export com os mesmos filtros que messages:list. A resposta retorna um identificador de tarefa uid imediatamente, antes que o arquivo seja gerado.
2. Consulte status com esse uid até que ele relate STATUS_SUCCESS (ou STATUS_FAILED).
3. Chame result com o mesmo uid para obter o nome do arquivo gerado.
4. Baixe o arquivo pelo nome.

Use lastTasks para procurar tarefas de exportação recentes para um aplicativo e delete para cancelar uma tarefa ou remover seu arquivo antecipadamente.

Métodos

O ciclo de vida da exportação tem cinco métodos, mais um endpoint de download simples:

Método	Descrição
exportMessagesStatistics/export	Enfileira uma exportação e retorna um uid de tarefa.
exportMessagesStatistics/status	Verifica o progresso da tarefa.
exportMessagesStatistics/result	Retorna o nome do arquivo gerado assim que a tarefa é concluída.
exportMessagesStatistics/lastTasks	Lista tarefas de exportação recentes para um aplicativo.
exportMessagesStatistics/delete	Cancela uma tarefa ou remove seu arquivo antes que o período de retenção expire.
Download	Baixa o arquivo CSV gerado pelo nome.

export

Enfileira uma exportação do histórico de mensagens e retorna um identificador de tarefa imediatamente.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export

Cabeçalhos

A solicitação precisa de um token de API do Servidor:

Nome	Obrigatório	Descrição
Authorization	Sim	Token de API do Servidor. Deve ser fornecido no seguinte formato: Authorization: Api <Server Key>.

Parâmetros do corpo da solicitação

O corpo da solicitação aceita os seguintes campos:

Nome	Obrigatório	Tipo	Descrição
type	Sim	String	Deve ser “TASK_TYPE_EXPORT_MESSAGES_V2”.
export_messages_v2	Sim	Object	Parâmetros de exportação, descritos abaixo.
export_messages_v2.application_code	Ver nota	String	Código do aplicativo Pushwoosh. Obrigatório se app_group_code não estiver definido.
export_messages_v2.app_group_code	Ver nota	String	Código do grupo de aplicativos, exporta para todos os aplicativos do grupo. Obrigatório se application_code não estiver definido.
export_messages_v2.search	Não	String	Pesquisa de texto livre no título e conteúdo da mensagem.
export_messages_v2.filters	Não	Object	Filtros de mensagem, descritos abaixo. Omita para exportar todo o histórico da conta.
export_messages_v2.properties	Não	Array	Colunas a serem incluídas no CSV, descritas abaixo.

export_messages_v2.filters aceita:

Nome	Tipo	Descrição
statuses	Array	Status da mensagem a serem incluídos. Valores possíveis ”MESSAGE_STATUS_CANCELED" "MESSAGE_STATUS_CREATING" "MESSAGE_STATUS_DONE" "MESSAGE_STATUS_FAIL" "MESSAGE_STATUS_PENDING" "MESSAGE_STATUS_PROCESSING" "MESSAGE_STATUS_WAITING”
platforms	Array	Códigos de plataforma (numéricos, ex. 1 para iOS), não as strings de nome de plataforma usadas por messages:list.
sent_date	Object	Período de relatório filtrado pela data de envio: {"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}.
created_date	Object	Período de relatório filtrado pela data de criação da mensagem, mesmo formato que sent_date.
created_via	Array	Origem da mensagem. Valores possíveis ”AB_TEST" "API" "AUTO_PUSH" "CP" "CSV" "CUSTOMER_JOURNEY" "EMAIL_API" "EMAIL_CP" "GEO_ZONE" "PUSH_ON_EVENT" "RSS" "SYSTEM”
segments	Array	Códigos de filtro para os quais a mensagem foi enviada.
campaigns	Array	Códigos de campanha. Ao contrário de messages:list, este aceita uma lista, não um único código.
message_id	String (uint64)	Um único ID de mensagem numérico, entre aspas. Ao contrário de messages:list, a exportação aceita um ID, não um array.
message_code	String	Um único código de mensagem.

export_messages_v2.properties seleciona quais colunas o CSV contém.

Valores possíveis

• "EXPORT_MESSAGE_PROPERTY_ID"
• "EXPORT_MESSAGE_PROPERTY_TIMESTAMP"
• "EXPORT_MESSAGE_PROPERTY_CONTENT"
• "EXPORT_MESSAGE_PROPERTY_TITLE"
• "EXPORT_MESSAGE_PROPERTY_APPLICATIONS"
• "EXPORT_MESSAGE_PROPERTY_STATUS"
• "EXPORT_MESSAGE_PROPERTY_PLATFORMS"
• "EXPORT_MESSAGE_PROPERTY_SOURCE"
• "EXPORT_MESSAGE_PROPERTY_FILTER"
• "EXPORT_MESSAGE_PROPERTY_SUBSCRIPTION_SEGMENTS"
• "EXPORT_MESSAGE_PROPERTY_SENT"
• "EXPORT_MESSAGE_PROPERTY_OPENED"
• "EXPORT_MESSAGE_PROPERTY_ERRORS"
• "EXPORT_MESSAGE_PROPERTY_RECIPIENTS"
• "EXPORT_MESSAGE_PROPERTY_DELIVERED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_DELIVERED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_OPENED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_CLICKS"
• "EXPORT_MESSAGE_PROPERTY_CLICKS"
• "EXPORT_MESSAGE_PROPERTY_UNSUBSCRIBED"

properties não é apenas um filtro

Uma propriedade não listada em properties não aparece no arquivo, incluindo as colunas base (ID, data de envio, conteúdo, status). Deixar properties vazio produz um CSV sem colunas. Liste todas as colunas que a exportação deve conter, não apenas as métricas que você deseja adicionar a um conjunto padrão.

Exemplo de solicitação

{
  "type": "TASK_TYPE_EXPORT_MESSAGES_V2",
  "export_messages_v2": {
    "application_code": "XXXXX-XXXXX",
    "filters": {
      "created_date": {
        "date_from": "2026-01-01",
        "date_to": "2026-06-30"
      },
      "statuses": ["MESSAGE_STATUS_DONE"],
      "platforms": [1, 3]
    },
    "properties": [
      "EXPORT_MESSAGE_PROPERTY_ID",
      "EXPORT_MESSAGE_PROPERTY_TIMESTAMP",
      "EXPORT_MESSAGE_PROPERTY_STATUS",
      "EXPORT_MESSAGE_PROPERTY_PLATFORMS",
      "EXPORT_MESSAGE_PROPERTY_SENT",
      "EXPORT_MESSAGE_PROPERTY_OPENED"
    ]
  }
}

200: OK

{
  "uid": "177458"
}

401: Incorrect API access token

{
  "error": "account not found"
}

status

Retorna o progresso de uma tarefa de exportação.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/status

Parâmetros do corpo da solicitação

Passe o identificador da tarefa retornado por export:

Nome	Obrigatório	Tipo	Descrição
uid	Sim	String (int64)	Identificador da tarefa da resposta de export, ex. "177458".

Exemplo de solicitação

{
  "uid": "177458"
}

200: OK

{
  "status": "STATUS_SUCCESS",
  "progress": 1
}

status é um de "STATUS_PENDING", "STATUS_SUCCESS", ou "STATUS_FAILED". progress é uma fração entre 0 e 1; consulte status até que atinja "STATUS_SUCCESS" antes de chamar result.

result

Retorna o nome do arquivo gerado assim que a tarefa for concluída.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/result

Parâmetros do corpo da solicitação

Passe o mesmo identificador de tarefa retornado por export:

Nome	Obrigatório	Tipo	Descrição
uid	Sim	String (int64)	Identificador da tarefa da resposta de export, ex. "177458".

Exemplo de solicitação

{
  "uid": "177458"
}

200: OK

{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}

Chamar result antes que status relate "STATUS_SUCCESS" retorna um resultado vazio. Passe o valor de file como está para o endpoint de download.

lastTasks

Lista as tarefas de exportação recentes para um aplicativo, da mais recente para a mais antiga.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/lastTasks

Parâmetros do corpo da solicitação

Cada parâmetro é um filtro opcional; omita todos eles para listar todas as tarefas às quais o token tem acesso:

Nome	Obrigatório	Tipo	Descrição
application	Não	String	Código do aplicativo Pushwoosh. Omita para listar tarefas de todos os aplicativos aos quais o token tem acesso.
types	Não	Array	Restringir a tipos de tarefa específicos. Use [“TASK_TYPE_EXPORT_MESSAGES_V2”] para ver apenas as exportações de mensagens.
campaign	Não	String	Filtrar por código de campanha.
message_id	Não	String (uint64)	Filtrar por um único ID de mensagem numérico, entre aspas.
message_code	Não	String	Filtrar por um único código de mensagem.
limit	Não	Integer	Número máximo de tarefas a serem retornadas.
timestamp_from	Não	String	Retornar apenas tarefas criadas após este timestamp (RFC 3339).

Nota

As tarefas são mantidas por 30 dias, independentemente de seu arquivo já ter sido excluído após o período de retenção de 7 dias. lastTasks ainda pode mostrar uma tarefa cujo result não resolve mais para um arquivo para download.

Exemplo de solicitação

{
  "application": "XXXXX-XXXXX",
  "types": ["TASK_TYPE_EXPORT_MESSAGES_V2"],
  "limit": 10
}

200: OK

{
  "tasks": [
    {
      "id": "177458",
      "timestamp": "2026-08-13T12:00:00Z",
      "status": "STATUS_SUCCESS",
      "requested_by_user": "user@example.com",
      "export_messages_v2": {
        "application_code": "XXXXX-XXXXX"
      },
      "export_messages_v2_result": {
        "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
      }
    }
  ]
}

delete

Exclui uma tarefa e seu arquivo antes que o período de retenção de 7 dias expire.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/delete

Parâmetros do corpo da solicitação

Passe o identificador da tarefa retornado por export:

Nome	Obrigatório	Tipo	Descrição
uid	Sim	String (int64)	Identificador da tarefa da resposta de export, ex. "177458".

Exemplo de solicitação

{
  "uid": "177458"
}

200: OK

{}

Download

Baixa o arquivo CSV gerado por result, pelo nome.

GET https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/<file>

Cabeçalhos

Autentique da mesma forma que os outros métodos, ou confie em uma sessão ativa do Painel de Controle:

Nome	Obrigatório	Descrição
Authorization	Sim	Token de API do Servidor, no mesmo formato que os outros métodos exportMessagesStatistics: Authorization: Api <Server Key> (o esquema Api não diferencia maiúsculas de minúsculas). Uma solicitação sem o cabeçalho Authorization e sem uma sessão de Painel de Controle logada recebe 401 Unauthorized.

Substitua <file> pelo valor exato de file da resposta de result, por exemplo:

https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv

O arquivo é um CSV contendo as colunas selecionadas em properties. Ele permanece disponível por 7 dias após o término da exportação, depois o trabalho de limpeza o remove e a URL para de resolver.