Статистика сообщений

messages:list

Отображает список отправленных сообщений.

POST https://api.pushwoosh.com/api/v2/messages:list

Заголовки

Имя	Обязательно	Описание
Authorization	Да	Server API token. Должен быть передан в следующем формате: Authorization: Api <Server Key>.

Параметры тела запроса

Имя	Обязательно	Тип	Описание
platforms	Нет	Array	Платформы сообщений. Возможные значения: "IOS", "ANDROID", "OSX", "WINDOWS", "AMAZON", "SAFARI", "CHROME", "FIREFOX", "IE", "EMAIL", "HUAWEI_ANDROID", "SMS".
date_range	Нет	Object	Отчетный период. date_from и date_to должны соответствовать формату YYYY-MM-DD (например, "2000-01-01").
campaign	Нет	String	Код кампании
filters	Да	Object	Фильтры сообщений.
source	Нет	String	Источник сообщения. Например: AB_TEST, API, AUTO_PUSH, CP, CSV, CUSTOMER_JOURNEY, EMAIL_API, EMAIL_CP, GEO_ZONE, PUSH_ON_EVENT, RSS.
messages_codes	Нет	Array	Коды сообщений, полученные из ответов API /createMessage.
messages_ids	Нет	Array	ID сообщений, полученные из Истории сообщений (Message History).
params	Нет	Object	Укажите, нужно ли показывать детали сообщения и метрики. Установите with_details: true, чтобы включить объект "details", и with_metrics: true, чтобы включить объект "metrics" в ответ.
application	Да	String	Код приложения Pushwoosh.
per_page	Нет	Integer	Количество результатов на странице (≤ 1000).
page	Нет	Integer	Номер страницы для пагинации.

Пример запроса

{
    "filters": {
      "platforms": [],                  // IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS
      "date_range": {
        "date_from": "string",          // Требуемый формат: 2000-01-01
        "date_to": "string"             // Требуемый формат: 2000-01-01
      },
      "source": "API",                  // AB_TEST, API, AUTO_PUSH, CP, CSV, CUSTOMER_JOURNEY, EMAIL_API, EMAIL_CP, GEO_ZONE, PUSH_ON_EVENT, RSS
      "campaign": "string",             // Код кампании
      "messages_ids": [],               // ID сообщений
      "messages_codes": [],             // Коды сообщений
      "application": "string"           // Код приложения Pushwoosh
    },
    "params": {
      "with_details": true,             // Добавить детали сообщения в ответ (объект "details")
      "with_metrics": true              // Добавить метрики сообщения в ответ (объект "metrics")
    },
    "per_page": 20,                     // <= 1000
    "page": 0
}

Коды ответов и примеры

200: OK

{
  "total": 0,
  "items": [{
    "id": 0,
    "code": "string",
    "created_date": "string",
    "send_date": "string",
    "status": "string",
    "platforms": [],
    "source": "string",
    "push_info": {
      "details": {
        "title": "string",
        "filter_name": "string",
        "filter_code": "string",
        "content": {
          "key": "value"
        },
        "platform_parameters": {
          "android_header": "string",
          "android_root_params": {
            "key": "value"
          },
          "ios_title": "string",
          "ios_subtitle": "string",
          "ios_root_params": {
            "key": "value"
          },
          "chrome_header": "string",
          "chrome_root_params": {
            "key": "value"
          },
          "firefox_header": "string",
          "firefox_root_params": {
            "key": "value"
          },
          "conditions": [               // условия тегов (см. /developer/api-reference/messages-api/#tag-conditions)
            TAG_CONDITION1,
            TAG_CONDITION2,
            ...,
            TAG_CONDITIONN
          ],
          "conditions_operator": "AND", // логический оператор для массивов условий; возможные значения: AND, OR
          "data": {
            "key": "value"
          }
        },
        "follow_user_timezone": true
      },
      "metrics": [{
        "sends": 0,
        "opens": 0,
        "deliveries": 0,
        "inbox_opens": 0,
        "unshowable_sends": 0,
        "errors": 0,
        "platform": 0
      }]
    },
    "email_info": {
      "details": {
        "template": "string",
        "filter_name": "string",
        "filter_code": "string",
        "subject": {
          "key": "value"
        },
        "from_name": "string",
        "from_email": "string",
        "reply_name": "string",
        "reply_email": "string",
        "follow_user_timezone": true,
        "conditions": [              // условия тегов (см. Messages-api - tag-conditions)
          TAG_CONDITION1,
          TAG_CONDITION2,
          ...,
          TAG_CONDITIONN
        ],
        "conditions_operator": "AND" // логический оператор для массивов условий; возможные значения: AND, OR
      },
      "metrics": [{
        "sends": 0,
        "opens": 0,
        "deliveries": 0,
        "hard_bounces": 0,
        "soft_bounces": 0,
        "rejects": 0,
        "confirmed_sends": 0,
        "unsubs": 0,
        "complaints": 0,
        "errors": 0
      }]
    }
  }]
}

400: Bad Request Error

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

401: Incorrect API access token

{
  "error": "account not found"
}

500: Internal Server Error

Примечание

Для iOS убедитесь, что вы добавили Notification Service Extension в свой проект для отслеживания доставки пушей. Подробнее

totalsByIntervals

Возвращает метрики и данные о конверсии на основе кода сообщения, агрегированные по часам.

POST https://api.pushwoosh.com/api/v2/statistics/messages/totalsByIntervals

Авторизация

Авторизация осуществляется через API Access Token в заголовке запроса.

Параметры тела запроса

Имя параметра	Тип	Описание	Обязательно
message_code	string	Код сообщения, полученный из ответов API /createMessage.	Да
platforms	[int]	Платформы	Нет

Пример запроса

{
  "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // обязательно. Уникальный идентификатор сообщения
  "platforms": [1, 3, 7, 10, 11, 12]          // необязательно. Список кодов платформ
}

Поля ответа

Имя	Тип	Описание
metrics	array	Содержит массив метрик сообщения
timestamp	string	Время метрики.
platform	int	Код платформы (например, iOS, Android).
sends	string	Количество отправленных сообщений.
opens	string	Количество открытых сообщений.
deliveries	string	Количество доставленных сообщений.
inbox_opens	string	Количество открытий из входящих (Inbox).
unshowable_sends	string	Количество отправленных сообщений, которые не удалось показать.
errors	string	Количество ошибок.
conversion	object	Содержит данные о конверсии
sends	string	Общее количество отправленных сообщений.
opens	string	Общее количество открытых сообщений.
events	array	Массив событий с их статистикой
name	string	Имя события (например, cart add).
hits	string	Количество срабатываний (hits).
conversion	float	Коэффициент конверсии относительно открытий.
revenue	float	Доход (только для событий с атрибутами __amount и __currency).

Пример ответа

{
  "metrics": [{
    "timestamp": "2024-08-03 15:00:00",  // Временная метка метрик в формате "YYYY-MM-DD HH:MM:SS"
    "platform": 3,                       // Код платформы
    "sends": "55902",                    // Количество отправленных сообщений
    "opens": "382",                      // Количество открытых сообщений
    "deliveries": "22931",               // Количество доставленных сообщений
    "inbox_opens": "0",                  // Количество сообщений, открытых во входящих
    "unshowable_sends": "2",             // Количество сообщений, которые не удалось показать
    "errors": "0"                        // Количество возникших ошибок
  }],
  "conversion": {
    "sends": "55902",                    // Общее количество отправленных сообщений
    "opens": "772",                      // Общее количество открытых сообщений
    "events": [{
      "name": "cart_add",                // Имя события
      "hits": "96",                      // Количество срабатываний события
      "conversion": 0.12,                // Коэффициент конверсии относительно открытий
      "revenue": 0                       // Доход, полученный от события (только для событий с атрибутами amount/currency)
    }]
  }
}

getMessageLog

Отображает подробную информацию об отправленных сообщениях.

POST https://api.pushwoosh.com/api/v2/statistics/getMessageLog

Заголовки

Имя	Обязательно	Описание
Authorization	Да	API access token из Pushwoosh Control Panel.

Параметры тела запроса

Имя	Обязательно	Тип	Описание
message_id	Нет	Integer	Выбор событий сообщений по Message ID, полученному из истории сообщений. Пример: 12345678900.
message_code	Нет	String	Выбор событий сообщений по Message code, полученному из ответов API /createMessage. Пример: "A444-AAABBBCC-00112233".
campaign_code	Нет	String	Выбор событий сообщений по Campaign code, указанному в полезной нагрузке сообщения. Пример: "AAAAA-XXXXX".
hwid	Нет	String или Array	Выбор событий сообщений по HWID (Hardware ID) или массиву HWID.
date_from	Обязательно, если не указаны message_id, message_code или campaign_code	Datetime	Дата начала фильтрации сообщений. Формат: "YYYY-MM-DD HH:MM:SS". Пример: "2000-01-25 00:00:00".
date_to	Обязательно, если не указаны message_id, message_code или campaign_code	Datetime	Дата окончания фильтрации сообщений. Формат: "YYYY-MM-DD HH:MM:SS". Пример: "2000-01-26 00:00:00".
limit	Нет	Integer	Максимальное количество событий сообщений, возвращаемых в одном ответе. Максимальное значение: 100000.
pagination_token	Нет	String	Токен пагинации, полученный из предыдущего ответа /getMessageLog. Используйте его для получения дополнительных результатов.
user_id	Нет	String	Выбор событий сообщений по пользовательскому User ID. См. /registerUser для подробностей.
application_code	Да	String	Выбор событий сообщений по коду приложения Pushwoosh
actions	Нет	Array	Фильтрация результатов по конкретным действиям с сообщениями. Возможные значения: "sent", "delivered", "opened", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted".
platforms	Нет	Array	Массив целевых платформ для фильтрации результатов. Возможные значения: "ios", "android", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "huawei_android".

Пример запроса

curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/getMessageLog' \
--header 'Authorization: Key API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "pagination_token": "PAGINATION_TOKEN_FROM_PREVIOUS_RESPONSE",  // необязательно, токен для пагинации
   "limit": 1000,                                  // необязательно, максимальное количество записей для одного ответа
   "application_code": "XXXXX-XXXXX",              // код приложения Pushwoosh
   "message_code": "A444-AAABBBCC-00112233",       // необязательно, код сообщения, полученный из запроса /createMessaage
   "message_id": 1234567890,                       // необязательно, ID сообщения, полученный из Pushwoosh Control Panel
   "campaign_code": "AAAAA-XXXXX",                 // необязательно, код кампании для получения лога
   "hwid": "aaazzzqqqqxxx",                        // необязательно, hardware ID конкретного устройства, на которое нацелено сообщение
   "user_id": "user_123",                          // необязательно, ID пользователя, на которого нацелено сообщение
   "date_from": "2000-01-25 00:00:00",             // необязательно, начало периода статистики
   "date_to": "2000-02-10 23:59:59",               // необязательно, конец периода статистики
   "actions": ["opened", "inbox_opened"],          // необязательно, используется для фильтрации результатов. Возможные значения: "sent", "opened", "delivered", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted". Ответ будет включать все сообщения с указанными действиями.
   "platforms": ["ios", "chrome"]                  // необязательно, используется для фильтрации результатов. Возможные значения: "ios", "android", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "huawei android"
}'

Важно

Одно из следующих полей обязательно:
- message_id
- message_code
- campaign_code
- hwid
- user_id
- date_from и date_to

Рекомендуется применять различные параметры фильтрации, чтобы получить максимум от статистики сообщений.

Коды ответов и примеры

200: OK

{
  "pagination_token": "PAGINATION_TOKEN_FOR_NEXT_REQUEST",
  "data": [{
    "timestamp": "2000-01-25T11:18:47Z",
    "application_code": "XXXXX-XXXXX",
    "message_id": 12345678900,
    "message_code": "A444-AAABBBCC-00112233",
    "campaign_code": "AAAAA-XXXXX",
    "hwid": "aaazzzqqqqxxx",
    "user_id": "user_123",
    "platform": "android",
    "action": "sent",
    "status": "success",
    "push_alerts_enabled": "true"
  }, {
    "timestamp": "2000-01-25T11:18:49Z",
    "application_code": "XXXXX-XXXXX",
    "message_id": 12345678900,
    "message_code": "A444-AAABBBCC-00112233",
    "campaign_code": "AAAAA-XXXXX",
    "hwid": "aaazzzqqqqxxx",
    "user_id": "user_123",
    "platform": "android",
    "action": "delivered",
    "push_alerts_enabled": "true"
  }, {
    "timestamp": "2000-01-25T11:19:23Z",
    "application_code": "XXXXX-XXXXX",
    "message_id": 12345678900,
    "message_code": "A444-AAABBBCC-00112233",
    "campaign_code": "AAAAA-XXXXX",
    "hwid": "aaazzzqqqqxxx",
    "user_id": "user_123",
    "platform": "android",
    "action": "opened",
    "push_alerts_enabled": "true"
  }]
}

400: Bad Request

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

401: Unauthorized

{
  "error": "account not found"
}

500: Internal Server Error

Примечание

Данные могут быть загружены максимум за 30 дней от текущего времени.

Совет

Для iOS убедитесь, что вы добавили Notification Service Extension в свой проект для отслеживания доставки пушей. Подробнее

Email statistics

linksInteractions

Отображает статистику кликов по ссылкам в email-сообщениях

POST https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions

Заголовки

Имя	Обязательно	Описание
Authorization	Да	API access token из Pushwoosh Control Panel.

Параметры тела запроса

Имя	Обязательно	Тип	Описание
date_range	Нет	Object	Определяет отчетный период. Содержит date_from и date_to.
filters	Да	Object	Фильтры email.
application	Да	String	Код приложения Pushwoosh (альтернативно, укажите campaign, messages_ids или message_codes).
messages_codes	Да	Array	Коды сообщений (альтернативно, укажите application, campaign или messages_ids).
campaign	Да	String	Код кампании (альтернативно, укажите application, messages_ids или message_codes).
messages_ids	Да	Array	ID сообщений (альтернативно, укажите application, campaign или message_codes).
link_template	Обязательно, если указаны application или campaign.	String	Фильтрует взаимодействия со ссылками в email по ключевому слову. В ответе API будут возвращены только ссылки, содержащие указанный текст в URL. Например, если ваш email содержит ссылки типа https://example.com/news и https://example.com/shop, установка “link_template”: “shop” вернет взаимодействия только для https://example.com/shop.
email_content_code	Нет	String	Уникальный идентификатор контента email.
params	Нет	Object	Определяет дополнительные параметры ответа. Включает with_full_links, который добавляет список полных ссылок со статистикой.

Пример запроса

curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions' \
--header 'Authorization: Api API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "filters": {
      "date_range": {
         "date_from": "string",           // Требуемый формат: 2000-01-01
         "date_to": "string"              // Требуемый формат: 2000-01-01
      },
      "campaign": "string",               // Код кампании (вместо этого можно указать application, messages_ids или message_codes)
      "application": "string",            // Код приложения (вместо этого можно указать campaign, messages_ids или message_codes)
      "messages_ids": [],                 // ID сообщений (вместо этого можно указать application, campaign или message_codes)
      "messages_codes": [],               // Коды сообщений (вместо этого можно указать application, campaign или message_ids)
      "link_template": "string",          // Шаблон ссылки (обязательно, если указаны application или campaign)
      "email_content_code": "string"      // Уникальный идентификатор контента email.
   },
   "params": {
      "with_full_links": true             // Укажите, нужно ли показывать подробную статистику. Список полных ссылок со статистикой будет передан в массиве full_links.
   }
}'

Коды ответов и примеры

200: OK

{
  "items": [{
    "template": "string",
    "link": "string",
    "title": "string",
    "clicks": 0,
    "full_links": [{
      "full_link": "string",
      "clicks": 0
    }]
  }]
}

400: Bad Request

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

401: Unauthorized

{
  "error": "account not found"
}

500: Internal Server Error

linksInteractionsDevices

Показывает пользователей, которые кликнули по ссылкам в email-сообщениях

POST https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractionsDevices

Заголовки

Имя	Обязательно	Описание
Authorization	Да	API access token из Pushwoosh Control Panel.

Параметры тела запроса

Имя	Обязательно	Тип	Описание
date_range	Нет	Object	Определяет отчетный период. Содержит date_from и date_to.
filters	Да	Object	Фильтры email.
application	Да	String	Код приложения Pushwoosh (альтернативно, укажите campaign, messages_ids или message_codes).
messages_codes	Да	Array	Коды сообщений (альтернативно, укажите application, campaign или messages_ids).
campaign	Да	String	Код кампании (альтернативно, укажите application, messages_ids или message_codes).
messages_ids	Да	Array	ID сообщений (альтернативно, укажите application, campaign или message_codes).
link_template	Обязательно, если указаны application или campaign.	String	Фильтрует взаимодействия со ссылками в email по ключевому слову. В ответе API будут возвращены только ссылки, содержащие указанный текст в URL. Например, если ваш email содержит ссылки типа https://example.com/news и https://example.com/shop, установка “link_template”: “shop” вернет взаимодействия только для https://example.com/shop.
email_content_code	Нет	String	Уникальный идентификатор контента email.
page	Нет	Integer	Номер страницы для пагинации.
per_page	Нет	Integer	Количество результатов на странице (≤ 1000).

Пример запроса

curl --location --request POST 'https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractionsDevices' \
--header 'Authorization: Api API_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "filters": {
      "date_range": {
         "date_from": "string",         // Требуемый формат: 2000-01-01
         "date_to": "string"            // Требуемый формат: 2000-01-01
      },
      "campaign": "string",             // Код кампании (вместо этого можно указать application, messages_ids или message_codes)
      "application": "string",          // Код приложения (вместо этого можно указать campaign, messages_ids или message_codes)
      "messages_ids": [],               // ID сообщений (вместо этого можно указать application, campaign или message_codes)
      "messages_codes": [],             // Коды сообщений (вместо этого можно указать application, campaign или message_ids)
      "link_template": "string",        // Шаблон ссылки (обязательно, если указаны application или campaign)
      "email_content_code": "string"    // Уникальный идентификатор контента email.
   },
   "per_page": 100,
   "page": 0
}'

Коды ответов и примеры

200: OK

{
  "total": 0,
  "items": [{
    "timestamp": "string",
    "link": "string",
    "hwid": "string"
  }]
}

400: Bad Request

{
  "error": "exceeded the maximum date interval. Max interval: 30 days"
}

401: Unauthorized

{
  "error": "account not found"
}

500: Internal Server Error

bouncedEmails

POST https://api.pushwoosh.com/api/v2/statistics/emails/bouncedEmails

Предоставляет данные о жалобах на email, мягких возвратах (soft bounces) и жестких возвратах (hard bounces), включая дату, email-адрес и причину каждого возврата.

Авторизация

Авторизация осуществляется через API Access Token в заголовке запроса.

Параметры тела запроса

Имя параметра	Тип	Описание	Обязательно
application	string	Код приложения Pushwoosh	Да
message_code	string	Код сообщения.	Обязательно, если не указаны date range или campaign
campaign	string	Код кампании.	Обязательно, если не указаны message_code или date range
date_from	string	Дата начала данных в формате YYYY-MM-DDTHH:MM:SS.000Z (стандарт ISO 8601).	Обязательно, если не указаны message_code или campaign
date_to	string	Дата окончания данных в формате YYYY-MM-DDTHH:MM:SS.000Z (стандарт ISO 8601).	Обязательно, если не указаны message_code или campaign
per_page	int	Количество строк на странице, максимум 5000.	Да
page	int	Номер страницы, начиная с нуля.	Да
type	string	Тип возврата: Complaint, Softbounce, Hardbounce.	Нет

Пример запроса

{
  "application": "XXXXX-XXXXX",               // обязательно. Код приложения Pushwoosh
  "message_code": "XXXXX-XXXXXXXXX-XXXXXXXX", // обязательно, если не указаны campaign или date range.
                                              //          Уникальный идентификатор сообщения
  "campaign": "XXXXX-XXXXX",                  // обязательно, если не указаны message_code или date range.
                                              //          Код кампании
  "date_from": "2024-07-20T00:00:00.000Z",    // обязательно, если не указаны message_code или campaign.
                                              //          Дата начала в формате ISO 8601 "YYYY-MM-DDTHH:MM:SS.SSSZ"
  "date_to": "2024-07-20T00:00:00.000Z",      // обязательно, если не указаны message_code или campaign.
                                              //          Дата окончания в формате ISO 8601 "YYYY-MM-DDTHH:MM:SS.SSSZ"
  "per_page": 1000,                           // обязательно. Количество результатов на странице, максимум 5000
  "page": 5,                                  // необязательно. Номер страницы, начиная с нуля
  "type": "Softbounce"                        // необязательно. Тип возврата: Complaint, Softbounce, Hardbounce
}

Поля ответа

Имя поля	Тип	Описание
total	int	Общее количество строк.
bounced_emails	array	Массив деталей возвращенных email.
├── email	string	Email-адрес, который вернулся.
├── date	string	Дата возврата (формат: YYYY-MM-DDTHH:MM:SS.000Z).
├── reason	string	Причина возврата.
└── type	string	Тип возврата: Complaint, Softbounce, Hardbounce.

Пример ответа

{
  "total": 25,                             // Общее количество строк.
  "bounced_emails": [{
    "email": "example@example.com",        // Email-адрес, который вернулся
    "date": "2024-07-20T00:00:00.000Z",    // Дата возврата в формате ISO 8601
    "reason": "Invalid recipient address", // Причина возврата
    "type": "Hardbounce"                   // Тип возврата: Complaint, Softbounce, Hardbounce
  }]
}