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_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 centro de datos correcto para la cuenta; úselo tal cual en lugar de construir la URL a partir de file usted mismo. file_url está vacío si el centro de datos de la cuenta no tiene una URL base configurada. En ese caso, solo puede recurrir a construir la URL a partir de file si la cuenta está en el centro de datos predeterminado app.pushwoosh.com; una cuenta en otro centro de datos o un dominio de marca blanca no tiene forma de derivar el host correcto solo a partir de file.

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 en el centro de datos predeterminado app.pushwoosh.com. Una cuenta en otro centro de datos (app.wavesend.ru para OVB, app.pushwoosh.us para IAD) o un dominio de marca blanca necesita un host diferente, y no hay forma de derivarlo solo a partir de file. Utilice la file_url de result o lastTasks en su lugar, porque ya apunta al host correcto para la cuenta. Consulte result para saber qué hacer si file_url llega vacía.

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.