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

exportMessagesStatistics exporta o histórico de mensagens e estatísticas 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 excederia o limite de paginação profunda de messages:list (page × per_page > 100000), ou quando o objetivo é 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 de 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 file gerado e uma file_url pronta para uso.
4. Faça o download do arquivo. Use a file_url como está, ou consulte result para construir a URL a partir de file se ela vier vazia.

Use lastTasks para procurar tarefas de exportação recentes para uma aplicação 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 as tarefas de exportação recentes para uma aplicação.
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 da API do Servidor:

Nome	Obrigatório	Descrição
Authorization	Sim	Token da 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 da aplicação 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 aplicações, exporta para todas as aplicações 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 das mensagens a serem incluídas. 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 de 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. Diferente 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. Diferente 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_CAMPAIGN_NAME"
• "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: Token de acesso à API incorreto

{
  "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 de tarefa retornado por export:

Nome	Obrigatório	Tipo	Descrição
uid	Sim	String (int64)	Identificador de 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 de 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",
    "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}

Chamar result antes que status relate "STATUS_SUCCESS" retorna um resultado vazio. file_url é um link pronto para uso para o endpoint de download no data center correto da conta — use-o como está em vez de construir a URL a partir de file por conta própria. file_url fica vazio se o data center da conta não tiver uma URL base configurada. Nesse caso, você só pode recorrer à construção da URL a partir de file se a conta estiver no data center padrão app.pushwoosh.com — uma conta em outro data center ou um domínio whitelabel não tem como derivar o host correto apenas de file.

lastTasks

Lista as tarefas de exportação recentes para uma aplicação, 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 para listar todas as tarefas às quais o token tem acesso:

Nome	Obrigatório	Tipo	Descrição
application	Não	String	Código da aplicação Pushwoosh. Omita para listar tarefas de todas as aplicações às 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",
        "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/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 de tarefa retornado por export:

Nome	Obrigatório	Tipo	Descrição
uid	Sim	String (int64)	Identificador de 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://app.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 da API do Servidor, no mesmo formato dos 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 logada no Painel de Controle recebe 401 Unauthorized.

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

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

Cuidado

Construir esta URL manualmente só funciona para contas no data center padrão app.pushwoosh.com. Uma conta em outro data center (app.wavesend.ru para OVB, app.pushwoosh.us para IAD) ou um domínio whitelabel precisa de um host diferente, e não há como derivá-lo apenas de file. Em vez disso, use a file_url de result ou lastTasks, pois ela já aponta para o host correto da conta. Consulte result para saber o que fazer se file_url vier vazia.

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, então o trabalho de limpeza o remove e a URL para de resolver.

Exportação de destinatários da mensagem

Os mesmos métodos export, status, result, lastTasks, delete e download também exportam os destinatários individuais de uma mensagem. Use "type": "TASK_TYPE_EXPORT_MESSAGE_RECIPIENTS" e um objeto export_message_recipients em vez de export_messages_v2.

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

Não é o Holdout Split do Customer Journey

Isto exporta os destinatários que uma mensagem excluiu. Um ponto Holdout Split do Customer Journey é um mecanismo diferente. Ele exclui usuários do restante de uma jornada antes de qualquer mensagem ser enviada, e sua tarefa exportJourneyPointUsers (os mesmos métodos export/status/result, com outro type) informa a participação nas ramificações, não os resultados de envio.

Campos de solicitação de export_message_recipients

Nome	Obrigatório	Tipo	Descrição
message_id	Ver nota	String (uint64)	Um único ID numérico de mensagem. Obrigatório se campaign não estiver definido.
campaign	Ver nota	String	Um único código da campanha. Obrigatório se message_id não estiver definido. Definir ambos restringe às linhas da mensagem dentro dessa campanha.
application	Sim	String	Código da aplicação à qual a mensagem pertence.
type	Sim	String	Quais destinatários exportar. Um de "sends", "deliveries", "opens", "holdout" (veja abaixo).
date_from / date_to	Não	String (date-time)	Restringe as linhas a esta janela. Omita ambos para obter todo o histórico da mensagem.

Omitir message_id e campaign ao mesmo tempo, ou omitir application, resulta em um erro que nomeia o campo ausente. Um message_id de outra conta resulta em NotFound: message not found, verificado antes da execução da exportação. Um message_id ou campaign que pertence a outra aplicação da mesma conta não é rejeitado. Ele não corresponde a nenhuma linha, e o CSV é baixado apenas com o cabeçalho.

type seleciona o conjunto de destinatários:

Valor	Linhas retornadas
"sends"	Todos os destinatários para os quais a mensagem foi aceita.
"deliveries"	Destinatários de sends cuja entrega o provedor confirmou.
"opens"	Destinatários de sends que abriram a mensagem.
"holdout"	Destinatários que esta mensagem excluiu, não qualquer outra mensagem. Nada foi enviado a eles. Tanto um grupo de controle em nível de conta quanto o holdout_percentage da própria mensagem (veja Messaging API v2) podem gerar esta linha.

Exemplo de solicitação

{
  "type": "TASK_TYPE_EXPORT_MESSAGE_RECIPIENTS",
  "export_message_recipients": {
    "message_id": "22875465358",
    "application": "6D382-5ADFE",
    "type": "holdout",
    "date_from": "2026-08-01T00:00:00Z",
    "date_to": "2026-09-30T00:00:00Z"
  }
}

200: OK

{
  "uid": "29820"
}

Consulte status e chame result da mesma forma que em uma exportação do histórico de mensagens. result retorna export_message_recipients_result em vez de export_messages_v2_result:

{
  "export_message_recipients_result": {
    "file": "Message_22875465358_Holdout_29820-fe5d8ba468df25b7.csv",
    "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Message_22875465358_Holdout_29820-fe5d8ba468df25b7.csv"
  }
}

sends, deliveries e opens compartilham um único conjunto de colunas: hwid, user_id, platform, send_timestamp, delivery_timestamp, open_timestamp, send_error, pae, send_status. pae é false quando a plataforma aceitou o envio, mas não exibiu nenhum alerta visível para ele, o mesmo caso que unshowable_sends contabiliza nas estatísticas agregadas. holdout tem seu próprio conjunto, mais curto: hwid, user_id, platform, holdout_timestamp.