Exportación asíncrona de estadísticas de mensajes

exportMessagesStatistics exporta el historial de mensajes y las estadísticas a un archivo CSV en el servidor. Utilícelo para extracciones grandes o de toda la cuenta que messages:list no puede manejar.

Cuándo usar la exportación en lugar de messages:list

Utilice messages:list para búsquedas en vivo y paginadas de un período delimitado. Utilice exportMessagesStatistics cuando el resultado excedería el límite de paginación profunda de messages:list (page × per_page > 100000), o cuando el objetivo es un único archivo descargable en lugar de un JSON paginado. La exportación no tiene límite en date_range o en el número de filas, porque transmite el resultado a un archivo en el disco en lugar de mantenerlo en una sola respuesta.

Cómo funciona el flujo de exportación

1. Llame a export con los mismos filtros que messages:list. La respuesta devuelve un identificador de tarea uid inmediatamente, antes de que se genere el archivo.
2. Sondee status con ese uid hasta que informe STATUS_SUCCESS (o STATUS_FAILED).
3. Llame a result con el mismo uid para obtener el file generado y una file_url lista para usar.
4. Descargue el archivo. Utilice file_url tal cual, o consulte result para construir la URL a partir de file si esta llegó vacía.

Utilice lastTasks para buscar tareas de exportación recientes para una aplicación, y delete para cancelar una tarea o eliminar su archivo antes de tiempo.

Métodos

El ciclo de vida de la exportación tiene cinco métodos, más un punto de conexión de descarga simple:

Método	Descripción
exportMessagesStatistics/export	Pone en cola una exportación y devuelve un uid de tarea.
exportMessagesStatistics/status	Comprueba el progreso de la tarea.
exportMessagesStatistics/result	Devuelve el nombre del archivo generado una vez que la tarea ha finalizado.
exportMessagesStatistics/lastTasks	Enumera las tareas de exportación recientes para una aplicación.
exportMessagesStatistics/delete	Cancela una tarea o elimina su archivo antes de que expire el período de retención.
Descargar	Descarga el archivo CSV generado por su nombre.

export

Pone en cola una exportación del historial de mensajes y devuelve un identificador de tarea de inmediato.

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

Cabeceras

La solicitud necesita un token de la API del servidor:

Nombre	Requerido	Descripción
Authorization	Sí	Token de la API del servidor. Debe proporcionarse en el siguiente formato: Authorization: Api <Server Key>.

Parámetros del cuerpo de la solicitud

El cuerpo de la solicitud acepta los siguientes campos:

Nombre	Requerido	Tipo	Descripción
type	Sí	String	Debe ser “TASK_TYPE_EXPORT_MESSAGES_V2”.
export_messages_v2	Sí	Object	Parámetros de exportación, descritos a continuación.
export_messages_v2.application_code	Ver nota	String	Código de aplicación de Pushwoosh. Requerido si no se establece app_group_code.
export_messages_v2.app_group_code	Ver nota	String	Código de grupo de aplicaciones, exporta a través de cada aplicación del grupo. Requerido si no se establece application_code.
export_messages_v2.search	No	String	Búsqueda de texto libre en el título y contenido del mensaje.
export_messages_v2.filters	No	Object	Filtros de mensajes, descritos a continuación. Omitir para exportar todo el historial de la cuenta.
export_messages_v2.properties	No	Array	Columnas a incluir en el CSV, descritas a continuación.

export_messages_v2.filters acepta:

Nombre	Tipo	Descripción
statuses	Array	Estados de los mensajes a incluir. Valores posibles ”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, p. ej., 1 para iOS), no las cadenas de nombres de plataforma utilizadas por messages:list.
sent_date	Object	Período de informe filtrado por fecha de envío: {"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}.
created_date	Object	Período de informe filtrado por fecha de creación del mensaje, mismo formato que sent_date.
created_via	Array	Origen del mensaje. Valores posibles ”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 a los que se envió el mensaje.
campaigns	Array	Códigos de campaña. A diferencia de messages:list, este toma una lista, no un único código.
message_id	String (uint64)	Un único ID de mensaje numérico, entre comillas. A diferencia de messages:list, la exportación toma un ID, no un array.
message_code	String	Un único código de mensaje.

export_messages_v2.properties selecciona qué columnas contiene el CSV.

Valores posibles

• "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 no es solo un filtro

Una propiedad que no figure en properties no aparecerá en el archivo en absoluto, incluidas las columnas base (ID, fecha de envío, contenido, estado). Dejar properties vacío produce un CSV sin columnas. Enumere todas las columnas que la exportación debe contener, no solo las métricas que desea agregar sobre un conjunto predeterminado.

Solicitud de ejemplo

{
  "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 acceso a la API incorrecto

{
  "error": "account not found"
}

status

Devuelve el progreso de una tarea de exportación.

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

Parámetros del cuerpo de la solicitud

Pase el identificador de tarea devuelto por export:

Nombre	Requerido	Tipo	Descripción
uid	Sí	String (int64)	Identificador de tarea de la respuesta de export, p. ej., "177458".

Solicitud de ejemplo

{
  "uid": "177458"
}

200: OK

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

status es uno de "STATUS_PENDING", "STATUS_SUCCESS", o "STATUS_FAILED". progress es una fracción entre 0 y 1; sondee status hasta que alcance "STATUS_SUCCESS" antes de llamar a result.

result

Devuelve el nombre del archivo generado una vez que la tarea ha finalizado.

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

Parámetros del cuerpo de la solicitud

Pase el mismo identificador de tarea devuelto por export:

Nombre	Requerido	Tipo	Descripción
uid	Sí	String (int64)	Identificador de tarea de la respuesta de export, p. ej., "177458".

Solicitud de ejemplo

{
  "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"
  }
}

Llamar a result antes de que status informe "STATUS_SUCCESS" devuelve un resultado vacío. file_url es un enlace listo para usar al punto de conexión de descarga en el host del centro de datos de la cuenta. Úselo tal cual en lugar de construir la URL a partir de file usted mismo. file_url está vacío si no hay una URL base de descarga configurada para el centro de datos de la cuenta. En ese caso, una URL construida a partir de file solo funciona para cuentas que inician sesión en app.pushwoosh.com.

lastTasks

Enumera las tareas de exportación recientes para una aplicación, de la más reciente a la más antigua.

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

Parámetros del cuerpo de la solicitud

Cada parámetro es un filtro opcional; omítalos todos para enumerar todas las tareas a las que el token tiene acceso:

Nombre	Requerido	Tipo	Descripción
application	No	String	Código de aplicación de Pushwoosh. Omitir para listar tareas en todas las aplicaciones a las que el token tiene acceso.
types	No	Array	Restringir a tipos de tareas específicos. Use [“TASK_TYPE_EXPORT_MESSAGES_V2”] para ver solo las exportaciones de mensajes.
campaign	No	String	Filtrar por código de campaña.
message_id	No	String (uint64)	Filtrar por un único ID de mensaje numérico, entre comillas.
message_code	No	String	Filtrar por un único código de mensaje.
limit	No	Integer	Número máximo de tareas a devolver.
timestamp_from	No	String	Solo devolver tareas creadas después de esta marca de tiempo (RFC 3339).

Nota

Las tareas se conservan durante 30 días, independientemente de si su archivo ya ha sido eliminado tras el período de retención de 7 días. lastTasks aún puede mostrar una tarea cuyo result ya no se resuelve en un archivo descargable.

Solicitud de ejemplo

{
  "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

Elimina una tarea y su archivo antes de que expire el período de retención de 7 días.

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

Parámetros del cuerpo de la solicitud

Pase el identificador de tarea devuelto por export:

Nombre	Requerido	Tipo	Descripción
uid	Sí	String (int64)	Identificador de tarea de la respuesta de export, p. ej., "177458".

Solicitud de ejemplo

{
  "uid": "177458"
}

200: OK

{}

Descargar

Descarga el archivo CSV generado por result, por su nombre.

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

Cabeceras

Autentícate de la misma manera que los otros métodos, o confía en una sesión activa del Panel de Control:

Nombre	Requerido	Descripción
Authorization	Sí	Token de la API del servidor, en el mismo formato que los otros métodos exportMessagesStatistics: Authorization: Api <Server Key> (el esquema Api no distingue entre mayúsculas y minúsculas). Una solicitud sin cabecera Authorization y sin una sesión iniciada en el Panel de Control obtiene un 401 Unauthorized.

Reemplace <file> con el valor exacto de file de la respuesta de result, por ejemplo:

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

Precaución

Construir esta URL manualmente solo funciona para cuentas que inician sesión en app.pushwoosh.com, porque el host no se puede deducir solo a partir de file. Use en su lugar el file_url de result o lastTasks, porque ya apunta al host del centro de datos de la cuenta. Consulte result para saber qué hacer si file_url llega vacío.

El archivo es un CSV que contiene las columnas seleccionadas en properties. Permanece disponible durante 7 días después de que finalice la exportación, luego el trabajo de limpieza lo elimina y la URL deja de resolverse.

Exportación de destinatarios de un mensaje

Los mismos métodos export, status, result, lastTasks, delete y download también exportan los destinatarios individuales de un mensaje. Use "type": "TASK_TYPE_EXPORT_MESSAGE_RECIPIENTS" y un objeto export_message_recipients en lugar de export_messages_v2.

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

No es el Holdout Split de Customer Journey

Esto exporta los destinatarios que un mensaje excluyó. Un punto Holdout Split de Customer Journey es un mecanismo distinto. Excluye usuarios del resto de un journey antes de que se envíe cualquier mensaje, y su tarea exportJourneyPointUsers (los mismos métodos export/status/result, con otro type) informa de la pertenencia a ramas, no de los resultados de envío.

Campos de la solicitud export_message_recipients

Nombre	Requerido	Tipo	Descripción
message_id	Véase la nota	String (uint64)	Un único ID numérico de mensaje. Obligatorio si no se define campaign.
campaign	Véase la nota	String	Un único código de campaña. Obligatorio si no se define message_id. Si se definen ambos, se limita a las filas del mensaje dentro de esa campaña.
application	Sí	String	Código de aplicación al que pertenece el mensaje.
type	Sí	String	Qué destinatarios exportar. Uno de "sends", "deliveries", "opens", "holdout" (véase más abajo).
date_from / date_to	No	String (date-time)	Limita las filas a esta ventana. Omita ambos para obtener todo el historial del mensaje.

Si se omiten tanto message_id como campaign, o se omite application, la solicitud falla con un error que nombra el campo que falta. Un message_id de otra cuenta falla con NotFound: message not found, comprobado antes de ejecutar la exportación. Un message_id o campaign que pertenece a otra aplicación de la misma cuenta no se rechaza. No coincide con ninguna fila, y el CSV se descarga solo con la fila de encabezado.

type selecciona el conjunto de destinatarios:

Valor	Filas devueltas
"sends"	Todos los destinatarios para los que se aceptó el mensaje.
"deliveries"	Destinatarios de sends cuya entrega confirmó el proveedor.
"opens"	Destinatarios de sends que abrieron el mensaje.
"holdout"	Destinatarios que este mensaje excluyó, no cualquier otro mensaje. No se les envió nada. Tanto un grupo de control de toda la cuenta como el holdout_percentage propio del mensaje (véase Messaging API v2) pueden producir esta fila.

Ejemplo de solicitud

{
  "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 y llame a result igual que en una exportación del historial de mensajes. result devuelve export_message_recipients_result en lugar 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 y opens comparten un mismo conjunto de columnas: hwid, user_id, platform, send_timestamp, delivery_timestamp, open_timestamp, send_error, pae, send_status. pae es false cuando la plataforma aceptó el envío pero no mostró ninguna alerta visible para él, el mismo caso que cuenta unshowable_sends en las estadísticas agregadas. holdout tiene su propio conjunto, más corto: hwid, user_id, platform, holdout_timestamp.