# Статистика сообщений ## messages:list Отображает список отправленных сообщений. `POST` `https://api.pushwoosh.com/api/v2/messages:list` ##### Заголовки | Имя
| Обязательно
| Описание
| |----------------|----------|------------------------------------------------------------------------------------------------------| | `Authorization`| Да | [Server API token](/ru/developer/api-reference/api-access-token/#server-api-token). Должен быть передан в следующем формате: `Authorization: Api `. | ##### Параметры тела запроса | Имя
| Обязательно
| Тип
| Описание
| |--------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------| | `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 | [Код кампании](/ru/developer/api-reference/api-identifiers/#campaign-code) | | `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 | [Коды сообщений](/ru/developer/api-reference/api-identifiers/#message-code), полученные из ответов API `/createMessage`. | | `messages_ids` | Нет | Array | ID сообщений, полученные из Истории сообщений (Message History). | | `params` | Нет | Object | Укажите, нужно ли показывать детали сообщения и метрики. Установите `with_details: true`, чтобы включить объект `"details"`, и `with_metrics: true`, чтобы включить объект `"metrics"` в ответ. | | `application` | Да | String | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code). | | `per_page` | Нет | Integer | Количество результатов на странице (≤ 1000). | | `page` | Нет | Integer | Номер страницы для пагинации. | ##### Пример запроса ```javascript { "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 } ```
Коды ответов и примеры ```javascript { "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 }] } }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ```
## totalsByIntervals Возвращает метрики и данные о конверсии на основе кода сообщения, агрегированные по часам. **POST** `https://api.pushwoosh.com/api/v2/statistics/messages/totalsByIntervals` ##### Авторизация Авторизация осуществляется через API Access Token в заголовке запроса. ##### Параметры тела запроса | Имя параметра
| Тип
| Описание | Обязательно | |----------------|--------|-----------------------------|----------| | `message_code` | string | [Код сообщения](/ru/developer/api-reference/api-identifiers/#message-code), полученный из ответов API `/createMessage`. | Да | | `platforms` | [int] | [Платформы](/ru/developer/api-reference/messages-api/api-prerequisites/#platforms) | Нет | ##### Пример запроса ```javascript { "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`). | ##### Пример ответа ```javascript { "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](/ru/developer/api-reference/api-access-token/) из Pushwoosh Control Panel. | ##### Параметры тела запроса | Имя
| Обязательно
| Тип
| Описание
| |--------------------|------------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `message_id` | Нет | Integer | Выбор событий сообщений по Message ID, полученному из истории сообщений. Пример: `12345678900`. | | `message_code` | Нет | String | Выбор событий сообщений по [Message code](/ru/developer/api-reference/api-identifiers/#message-code), полученному из ответов API `/createMessage`. Пример: `"A444-AAABBBCC-00112233"`. | | `campaign_code` | Нет | String | Выбор событий сообщений по [Campaign code](/ru/developer/api-reference/api-identifiers/#campaign-code), указанному в полезной нагрузке сообщения. Пример: `"AAAAA-XXXXX"`. | | `hwid` | Нет | String или Array | Выбор событий сообщений по [HWID (Hardware ID)](/ru/developer/api-reference/api-identifiers/#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](/ru/developer/api-reference/api-identifiers/#user-id). См. `/registerUser` для подробностей. | | `application_code` | Да | String | Выбор событий сообщений по [коду приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) | | `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"`. | ##### Пример запроса ```shell 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" }' ```
Коды ответов и примеры ```json { "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" }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ```
## Email statistics ### linksInteractions Отображает статистику кликов по ссылкам в email-сообщениях `POST` `https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractions` ##### Заголовки | Имя
| Обязательно
| Описание | |-----------------|----------|-------------------------------------------------------------------------------------------------------| | `Authorization` | Да | [API access token](/ru/developer/api-reference/api-access-token/) из Pushwoosh Control Panel. | ##### Параметры тела запроса | Имя
| Обязательно
| Тип | Описание | |--------------------|----------|--------|------------------------------------------------------------------------------------------------------| | `date_range` | Нет | Object | Определяет отчетный период. Содержит `date_from` и `date_to`. | | `filters` | Да | Object | Фильтры email. | | `application` | Да | String | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) (альтернативно, укажите `campaign`, `messages_ids` или `message_codes`). | | `messages_codes` | Да | Array | [Коды сообщений](/ru/developer/api-reference/api-identifiers/#message-code) (альтернативно, укажите `application`, `campaign` или `messages_ids`). | | `campaign` | Да | String | [Код кампании](/ru/developer/api-reference/api-identifiers/#campaign-code) (альтернативно, укажите `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](/ru/developer/api-reference/api-identifiers/#email-content-code). | | `params` | Нет | Object | Определяет дополнительные параметры ответа. Включает `with_full_links`, который добавляет список полных ссылок со статистикой. | ##### Пример запроса ```shell 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. } }' ``` ##### Коды ответов и примеры ```json { "items": [{ "template": "string", "link": "string", "title": "string", "clicks": 0, "full_links": [{ "full_link": "string", "clicks": 0 }] }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ``` ### linksInteractionsDevices Показывает пользователей, которые кликнули по ссылкам в email-сообщениях `POST` `https://api.pushwoosh.com/api/v2/statistics/emails/linksInteractionsDevices` ##### Заголовки | Имя
| Обязательно
| Описание | |-----------------|----------|------------------------------------------------------------------------------------------------------| | `Authorization` | Да | [API access token](/ru/developer/api-reference/api-access-token/) из Pushwoosh Control Panel. | ##### Параметры тела запроса | Имя
| Обязательно
| Тип | Описание | |--------------------|----------|---------|------------------------------------------------------------------------------------------------------| | `date_range` | Нет | Object | Определяет отчетный период. Содержит `date_from` и `date_to`. | | `filters` | Да | Object | Фильтры email. | | `application` | Да | String | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) (альтернативно, укажите `campaign`, `messages_ids` или `message_codes`). | | `messages_codes` | Да | Array | [Коды сообщений](/ru/developer/api-reference/api-identifiers/#message-code) (альтернативно, укажите `application`, `campaign` или `messages_ids`). | | `campaign` | Да | String | [Код кампании](/ru/developer/api-reference/api-identifiers/#campaign-code) (альтернативно, укажите `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](/ru/developer/api-reference/api-identifiers/#email-content-code). | | `page` | Нет | Integer | Номер страницы для пагинации. | | `per_page` | Нет | Integer | Количество результатов на странице (≤ 1000). | ##### Пример запроса ```shell 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 }' ``` ##### Коды ответов и примеры ```json { "total": 0, "items": [{ "timestamp": "string", "link": "string", "hwid": "string" }] } ``` ```json { "error": "exceeded the maximum date interval. Max interval: 30 days" } ``` ```json { "error": "account not found" } ``` ### bouncedEmails **POST** `https://api.pushwoosh.com/api/v2/statistics/emails/bouncedEmails` Предоставляет данные о жалобах на email, мягких возвратах (soft bounces) и жестких возвратах (hard bounces), включая дату, email-адрес и причину каждого возврата. ##### Авторизация Авторизация осуществляется через API Access Token в заголовке запроса. ##### Параметры тела запроса | Имя параметра | Тип | Описание | Обязательно | |----------------|--------|--------------------------------------------------------------------------------------------------|------------------------------------------------| | `application` | string | [Код приложения Pushwoosh](/ru/developer/api-reference/api-identifiers/#application-code) | Да | | `message_code` | string | [Код сообщения](/ru/developer/api-reference/api-identifiers/#message-code). | Обязательно, если не указаны `date range` или `campaign` | | `campaign` | string | [Код кампании](/ru/developer/api-reference/api-identifiers/#campaign-code). | Обязательно, если не указаны `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. | Нет | ##### Пример запроса ```javascript { "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. | ##### Пример ответа ```javascript { "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 }] } ```