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

messages:list

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

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

Заголовки

Имя	Обязательный	Описание
Authorization	Да	Токен Server API. Должен быть предоставлен в следующем формате: 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 должны соответствовать формату ГГГГ-ММ-ДД (например, "2000-01-01"); оба дня включаются полностью, поэтому date_from и date_to, установленные на одну и ту же дату, возвращают весь этот день. Даты интерпретируются в UTC, а не в часовом поясе вашего аккаунта.
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 сообщений, полученные из истории сообщений
params	Нет	Object	Укажите, следует ли показывать детали и метрики сообщения. Установите with_details: true, чтобы включить объект "details", и with_metrics: true, чтобы включить объект "metrics" в ответ.
application	Да	String	Код приложения Pushwoosh.
per_page	Нет	Integer	Количество результатов на странице, от 1 до 499. Опустите параметр, чтобы получить размер страницы по умолчанию в 500 результатов; передача 500 или более явным образом отклоняется с кодом 400.
page	Нет	Integer	Номер страницы для пагинации, начиная с нуля. См. ограничение на глубокую пагинацию ниже.

Глубокая пагинация

messages:list отклоняет запросы, в которых page × per_page превышает 100 000 результатов. Сузьте date_range или используйте меньшее значение per_page, чтобы оставаться в пределах лимита.

total — это точное количество сообщений, соответствующих фильтрам, пока это число не превышает 100 000, и останавливается на 100001 выше этого значения — больше, чем этот эндпоинт может обработать постранично. Не создавайте цикл постраничной выгрузки за пределами этого лимита: страницы за его пределами будут отклонены, а не пусты. Чтобы выгрузить период, содержащий больше сообщений, сузьте date_range для каждого запроса или используйте асинхронный экспорт, который записывает весь период в один CSV-файл без постраничной разбивки.

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

{
    "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,                     // <= 499
    "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: Ошибка неверного запроса

date_range охватывает более 30 дней:

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

page × per_page превышает лимит глубокой пагинации:

{
  "error": "requested result window is too large, narrow the date range"
}

401: Неверный токен доступа API

{
  "error": "account not found"
}

500: Внутренняя ошибка сервера

Примечание

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

totalsByIntervals

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

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

Авторизация

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

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

Имя параметра	Тип	Описание	Обязательный
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	Количество открытий из Message Inbox.
unshowable_sends	string	Количество сообщений, принятых для устройств с отключенными уведомлениями в настройках ОС. Баннер не отображается, но сообщение все равно доходит до приложения и появляется в Message Inbox, если для отправки включена опция Сохранить сообщение в Message Inbox. Учитывается как успешная отправка, а не как ошибка.
errors	string	Количество ошибок.
conversion	object	Содержит данные о конверсии
sends	string	Общее количество отправленных сообщений.
opens	string	Общее количество открытых сообщений.
events	array	Массив событий с их статистикой
name	string	Название события (например, добавление в корзину).
hits	string	Количество хитов.
conversion	float	Коэффициент конверсии относительно открытий.
revenue	float	Доход (только для событий с атрибутами __amount и __currency).

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

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

Воронка доставки

Используйте воронку доставки, чтобы увидеть, на каком этапе сообщение или кампания потеряли аудиторию (ошибки, отсутствие доставки, отсутствие открытия) и почему. В отличие от totalsByIntervals, который возвращает почасовые итоги, воронка разбивает аудиторию по этапам и причинам выбывания, по одной записи на канал, с разбивкой по платформам. Последовательность этапов зависит от канала: см. stage в разделе Поля GetDeliveryFunnelResponse ниже, чтобы узнать, какие этапы несёт каждый канал. Оба метода требуют серверного API-токена.

Не ограничено приложением токена

Ограничение токена по приложению не применяется к этим двум методам. Они возвращают воронку для любого message_code или campaign_code, принадлежащего аккаунту токена, независимо от того, к какому приложению ограничен токен. Это сделано намеренно.

Оба метода возвращают один и тот же формат ответа, GetDeliveryFunnelResponse, описанный один раз ниже.

getDeliveryFunnel

Возвращает воронку одного сообщения.

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

Заголовки

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

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

Название	Обязательно	Тип	Описание
message_code	Да	Строка	Код сообщения, полученный из ответов API /createMessage.
platforms	Нет	Массив целых чисел	Коды платформ для фильтрации воронки. Не указывайте, чтобы вернуть все платформы, на которые было отправлено сообщение.

Примечание

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

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

{
  "message_code": "A444-AAABBBCC-00112233",  // Код сообщения из /createMessage
  "platforms": [1, 14]                        // Необязательно. iOS, Email
}

Каждое поле всегда присутствует

Каждое описанное ниже поле присутствует в каждом ответе, даже при нулевом значении: пустой массив ("pieces": []), неустановленное перечисление в виде значения _UNSPECIFIED или неустановленная метка времени в виде null. Значение имеет смысл, а не то, присутствует ли поле. Поля count сериализуются как строки JSON, например "count": "9820", а не как числа. platform и code остаются обычными числами.

Поля GetDeliveryFunnelResponse

Название	Тип	Описание
channels	Массив	По одной записи на каждый канал, по которому было отправлено сообщение.
window_from, window_to	Строка или null	Период, который охватывает воронка, на основе доступных данных. null, когда funnel_state не равен FUNNEL_STATE_READY.
funnel_state	Строка	FUNNEL_STATE_READY: воронка ниже заполнена. FUNNEL_STATE_NO_EVENTS: для этого сообщения пока ничего не произошло. FUNNEL_STATE_EXPIRED: сообщение было отправлено слишком давно. Данные воронки для него больше недоступны. channels пуст в обоих случаях, кроме READY. Неизвестный, чужой или удалённый message_code — не один из этих статусов, см. ответ 404 ниже.

channels[]

Название	Тип	Описание
channel	Строка	CHANNEL_MOBILE_PUSH (iOS, macOS, Android, Amazon, Huawei), CHANNEL_WEB_PUSH (Safari, Chrome, Firefox), CHANNEL_EMAIL, CHANNEL_OTHER (SMS, мессенджеры, Wallet, Windows, Baidu, Xiaomi), CHANNEL_APP_INBOX.
funnel	Массив	Этапы воронки для этого канала, см. funnel[] ниже.
deliveries_form	Строка	Какую разбивку несёт этап STAGE_DELIVERIES: DELIVERIES_FORM_PER_DEVICE (четыре непересекающихся строки, разбитые по тому, показало бы устройство алерт и подтвердило ли оно доставку) или DELIVERIES_FORM_BASIC (две строки, без разбивки по состоянию алерта).
basic_form_reason	Строка	Имеет значение только когда deliveries_form равен DELIVERIES_FORM_BASIC: BASIC_FORM_REASON_RETENTION (сообщение слишком старое для разбивки по устройствам), BASIC_FORM_REASON_UNAVAILABLE (разбивка по устройствам недоступна для этого аккаунта или сообщения, например системного), BASIC_FORM_REASON_NO_DELIVERIES (пока ничего не принято), BASIC_FORM_REASON_NOT_APPLICABLE (у канала вообще нет состояния алерта, например email или App Inbox). Иначе BASIC_FORM_REASON_UNSPECIFIED: игнорируйте это поле, если deliveries_form не равен DELIVERIES_FORM_BASIC.
confirmed_deliveries	Объект	count и разбивка подтверждённых доставок по platforms. Не ограничено значением этапа STAGE_DELIVERIES, поэтому может от него отличаться.

funnel[] (один этап)

Название	Тип	Описание
stage	Строка	STAGE_AUDIENCE (все, на кого было нацелено сообщение), STAGE_SENT (принято push-сервисом или email-провайдером), STAGE_ERRORS (отклонено до принятия), STAGE_DELIVERIES (принято, с разбивкой по подтверждению), STAGE_OPENED (уникальные устройства, открывшие сообщение, а для App Inbox — записи, которые пользователь открыл нажатием), STAGE_INTERACTIONS (только email: клик, отписка, жалоба), STAGE_REACHED/STAGE_READ (только App Inbox, заменяют STAGE_DELIVERIES).
count	Строка	Итог по этапу в виде числовой строки.
pieces	Массив	Собственная разбивка этапа. Пусто для STAGE_ERRORS, где вместо этого используется errors. Каждый элемент содержит kind (KIND_PASSED — перешёл на следующий этап, KIND_REASON — не перешёл, KIND_SUBSET — пересекается с двумя другими и никогда не суммируется), category (см. список значений ниже для каждого этапа), count и разбивку по platforms.
errors	Массив	Только для STAGE_ERRORS: category (см. список значений ниже), count, platforms и codes: необработанные коды ошибок провайдера, сгруппированные в эту категорию (platform, code, name, count).
platforms	Массив	Итог этапа с разбивкой по платформам.

Значения category

STAGE_AUDIENCE:

• ELIGIBLE_AUDIENCE (перешёл): не исключён ни по одной из причин ниже.
• FREQUENCY_CAPPING: пропущен из-за ограничения частоты.
• CONTROL_GROUP: выделен в контрольную группу.
• UNSUBSCRIBED: получатель отписался.
• BOUNCED: адрес получателя ранее возвращался с ошибкой.
• COMPLAINT: получатель ранее отметил сообщение как спам.
• FILTERED_BY_CATEGORY: получатель отказался от этой категории сообщений.

STAGE_ERRORS:

• NO_TOKEN: у устройства не было push-токена или адреса для отправки.
• NO_DEVICE: не найдено подходящее устройство.
• PLATFORM_DISABLED: платформа отключена для этого приложения.
• INVALID_TOKEN: провайдер отклонил токен устройства или адрес как недействительный.
• QUOTA_EXCEEDED: провайдер ограничил скорость отправки.
• INVALID_CONTENT: сообщение не удалось отправить в собранном виде. Чаще всего не собрался сам шаблон, например сломанный блок Connected Content или Liquid, а не отклонение провайдером.
• INVALID_CONFIGURATION: сломана собственная настройка провайдера аккаунта, например неверные учётные данные, удалённый проект Firebase или запрещённый топик APNs.
• PROVIDER_ERROR: провайдер вернул ошибку вне категорий выше.
• INTERNAL_ERROR: Pushwoosh не смог обработать отправку.
• UNCLASSIFIED_ERROR: выбывание, не подходящее ни под одну из категорий выше. Ожидается редко.

STAGE_DELIVERIES, DELIVERIES_FORM_PER_DEVICE:

• DISPLAYABLE_CONFIRMED (перешёл): устройство показало алерт и подтвердило получение.
• DISPLAYABLE_NO_CONFIRMATION: устройство должно было показать алерт, но ещё не подтвердило получение.
• NOT_DISPLAYABLE_CONFIRMED (перешёл): тихий push подтвердил получение.
• NOT_DISPLAYABLE_NO_CONFIRMATION: тихий push ещё не подтвердил получение.

STAGE_DELIVERIES, DELIVERIES_FORM_BASIC:

• CONFIRMED_BY_DEVICE (перешёл): устройство подтвердило получение.
• NO_CONFIRMATION: пока не подтверждено.

Email дополнительно добавляет, как подмножество, пересекающееся с CONFIRMED_BY_DEVICE:

• BOUNCED_HARD (подмножество): адрес постоянно недоступен для доставки.
• BOUNCED_SOFT (подмножество): адрес временно недоступен для доставки, например переполненный почтовый ящик.

BOUNCED_HARD может также разбиваться на следующие строки подмножества:

• BOUNCED_HARD_GENERAL: постоянно недоступен, более точная причина недоступна.
• BOUNCED_HARD_MAILBOX_FULL: почтовый ящик получателя переполнен.
• BOUNCED_HARD_MAILBOX_INACTIVE: почтовый ящик получателя больше не существует.
• BOUNCED_HARD_SUPPRESSED: адрес занесён провайдером в чёрный список.
• BOUNCED_HARD_UNDETERMINED: постоянно недоступен, причина не определена.

BOUNCED_SOFT может также разбиваться на следующие строки подмножества:

• BOUNCED_SOFT_GENERAL: временно недоступен, более точная причина недоступна.
• BOUNCED_SOFT_MAILBOX_FULL: почтовый ящик получателя был переполнен на момент отправки.
• BOUNCED_SOFT_CONTENT_REJECTED: почтовый сервер получателя отклонил содержимое сообщения.
• BOUNCED_SOFT_SPAM: почтовый сервер получателя пометил сообщение как спам.
• BOUNCED_SOFT_MESSAGE_TOO_LARGE: сообщение было слишком большим для почтового ящика получателя.
• BOUNCED_SOFT_ATTACHMENT_REJECTED: почтовый сервер получателя отклонил вложение.
• BOUNCED_SOFT_CUSTOM_TIMEOUT_EXCEEDED: почтовый сервер получателя слишком долго отвечал.
• BOUNCED_SOFT_UNDETERMINED: временно недоступен, причина не определена.
• BOUNCED_UNDETERMINED: сервер получателя принял письмо, но так и не подтвердил доставку; результат неизвестен, и адрес не заблокирован. Считается мягким отказом.

BOUNCED_UNCLASSIFIED — отказ, жёсткий или мягкий, не подходящий ни под один из подтипов выше. Ожидается редко и не является значением, на котором стоит строить логику.

STAGE_OPENED, только email (другие каналы сообщают count этапа без элементов):

• OPENED_BY_RECIPIENT (перешёл): открыто человеком.
• MACHINE_OPENS_ONLY: открыто только автоматическим сканером.
• OPEN_TYPE_UNKNOWN: не удалось классифицировать как открытие человеком или сканером.
• MACHINE_OPENS_AMPP (подмножество): заменяет три строки выше, когда разбивка человек/сканер недоступна для этого сообщения. Вместо этого учитывает собственное число машинных открытий Apple Mail Privacy Protection и пересекается с итогом этапа.

STAGE_INTERACTIONS, только email:

• CLICKED_ONLY (перешёл): кликнул по ссылке, остался подписан.
• CLICKED_AND_UNSUBSCRIBED: кликнул по ссылке и отписался.
• CLICKED_AND_COMPLAINED: кликнул по ссылке и отметил сообщение как спам.
• UNSUBSCRIBED_WITHOUT_CLICK: отписался без клика.
• COMPLAINED_WITHOUT_CLICK: отметил сообщение как спам без клика.

STAGE_REACHED, только App Inbox:

• REACHED (перешёл): запись была получена приложением хотя бы раз.
• NOT_FETCHED_YET: ещё не получена.

STAGE_READ, только App Inbox:

• READ (перешёл): отмечена как прочитанная.
• DISMISSED_UNREAD: удалена пользователем без прочтения.
• UNREAD: всё ещё лежит непрочитанной во входящих.
• EXPIRED_UNREAD: то же самое, что UNREAD, но запись с тех пор истекла и исчезла из входящих.
• DISMISSED (подмножество): каждая удалённая запись, прочитанная или нет. Пересекается с READ и DISMISSED_UNREAD.

Коды ответов

200: OK

{
  "channels": [{
    "channel": "CHANNEL_MOBILE_PUSH",
    "funnel": [
      { "stage": "STAGE_AUDIENCE", "count": "10000", "pieces": [
        { "kind": "KIND_PASSED", "category": "ELIGIBLE_AUDIENCE", "count": "10000", "platforms": [{ "platform": 1, "count": "10000" }] }
      ], "errors": [], "platforms": [{ "platform": 1, "count": "10000" }] },
      { "stage": "STAGE_SENT", "count": "9820", "pieces": [], "errors": [], "platforms": [{ "platform": 1, "count": "9820" }] },
      { "stage": "STAGE_ERRORS", "count": "180", "pieces": [], "errors": [
        { "category": "INVALID_TOKEN", "count": "180", "platforms": [{ "platform": 1, "count": "180" }], "codes": [
          { "platform": 1, "code": 1002, "name": "BadDeviceToken", "count": "180" }
        ] }
      ], "platforms": [{ "platform": 1, "count": "180" }] },
      { "stage": "STAGE_DELIVERIES", "count": "9820", "pieces": [
        { "kind": "KIND_PASSED", "category": "DISPLAYABLE_CONFIRMED", "count": "8000", "platforms": [{ "platform": 1, "count": "8000" }] },
        { "kind": "KIND_REASON", "category": "DISPLAYABLE_NO_CONFIRMATION", "count": "820", "platforms": [{ "platform": 1, "count": "820" }] },
        { "kind": "KIND_PASSED", "category": "NOT_DISPLAYABLE_CONFIRMED", "count": "900", "platforms": [{ "platform": 1, "count": "900" }] },
        { "kind": "KIND_REASON", "category": "NOT_DISPLAYABLE_NO_CONFIRMATION", "count": "100", "platforms": [{ "platform": 1, "count": "100" }] }
      ], "errors": [], "platforms": [{ "platform": 1, "count": "9820" }] },
      { "stage": "STAGE_OPENED", "count": "3120", "pieces": [], "errors": [], "platforms": [{ "platform": 1, "count": "3120" }] }
    ],
    "deliveries_form": "DELIVERIES_FORM_PER_DEVICE",
    "basic_form_reason": "BASIC_FORM_REASON_UNSPECIFIED",
    "confirmed_deliveries": { "count": "8900", "platforms": [{ "platform": 1, "count": "8900" }] }
  }],
  "window_from": "2026-09-01T00:00:00Z",
  "window_to": "2026-09-01T00:05:00Z",
  "funnel_state": "FUNNEL_STATE_READY"
}

Пустой массив channels с funnel_state: "FUNNEL_STATE_NO_EVENTS" означает, что для этого сообщения пока ничего не произошло. Это не ошибка. message_code, отправленный слишком давно для доступности данных воронки, также возвращает 200, с пустым массивом channels и funnel_state: "FUNNEL_STATE_EXPIRED".

404: Message not found

Неизвестный message_code, принадлежащий другому аккаунту, или уже удалённый:

{
  "error": "message not found"
}

401: Invalid or missing token

{
  "error": "invalid auth token"
}

500: Internal Server Error

getCampaignDeliveryFunnel

Суммирует getDeliveryFunnel по всем сообщениям кампании. Уникальные подсчёты вычисляются по каждому сообщению отдельно: подписчик, охваченный несколькими сообщениями кампании, учитывается один раз для каждого сообщения.

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

Заголовки

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

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

Название	Обязательно	Тип	Описание
campaign_code	Да	Строка	Код кампании.
platforms	Нет	Массив целых чисел	Коды платформ для фильтрации воронки. Не указывайте, чтобы вернуть все платформы, на которые была отправлена кампания.

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

{
  "campaign_code": "AAAAA-XXXXX",  // Код кампании
  "platforms": [1, 14]             // Необязательно. iOS, Email
}

Ответ

Тот же формат, что и GetDeliveryFunnelResponse выше.

Коды ответов

200: OK

Пустая аудитория для указанных campaign_code и platforms также возвращает 200 с пустым массивом channels и funnel_state: "FUNNEL_STATE_NO_EVENTS". Кампания, отправленная слишком давно для доступности данных воронки, также возвращает 200, с пустым массивом channels и funnel_state: "FUNNEL_STATE_EXPIRED". Ни то, ни другое не является ошибкой.

404: Campaign not found

Неизвестный campaign_code, принадлежащий другому аккаунту, или тот, все сообщения которого были удалены. Кампания, у которой удалена только часть сообщений, не затрагивается: удалённые сообщения всё равно учитываются в её воронке.

{
  "error": "campaign not found"
}

401: Invalid or missing token

{
  "error": "invalid auth token"
}

500: Internal Server Error

getMessageLog

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

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

Заголовки

Имя	Обязательный	Описание
Authorization	Обязательно	Токен доступа API из Control Panel Pushwoosh.

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

Имя	Обязательный	Тип	Описание
message_id	Нет	Integer	Выбор событий сообщений по ID сообщения, полученному из истории сообщений. Пример: 12345678900.
message_code	Нет	String	Выбор событий сообщений по коду сообщения, полученному из ответов API /createMessage. Пример: "A444-AAABBBCC-00112233".
campaign_code	Нет	String	Выбор событий сообщений по коду кампании, указанному в полезной нагрузке вашего сообщения. Пример: "AAAAA-XXXXX".
hwid	Нет	String or Array	Выбор событий сообщений по HWID (Hardware ID) или массиву HWID.
date_from	Обязательно, если не указаны message_id, message_code или campaign_code	Datetime	Начальная дата для фильтрации сообщений. Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС". Пример: "2000-01-25 00:00:00".
date_to	Обязательно, если не указаны message_id, message_code или campaign_code	Datetime	Конечная дата для фильтрации сообщений. Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС". Пример: "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", "reject", "create", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted". События "create" по умолчанию исключаются из ответа. Включите "create" в этот массив, чтобы их увидеть. Для событий "delivered" дополнительно требуется, чтобы в аккаунте была включена статистика доставки.
platforms	Нет	Array	Массив целевых платформ для фильтрации результатов. Возможные значения: "unknown", "ios", "blackberry", "android", "windows phone", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "fb messenger", "baidu android", "huawei android", "sms", "xiaomi", "web", "whatsapp", "line", "kakao", "telegram", "apple wallet", "google wallet", "viber".
message_type	Нет	String	Фильтрация результатов по потоку сообщений. "all" (по умолчанию, если не указано) возвращает все, "broadcast" возвращает только массовые сообщения (message_id != 0), "transactional" возвращает только сообщения с message_id = 0, включая те, что отправлены из Customer Journey.

Значения платформ чувствительны к регистру

Передавайте значения platforms в нижнем регистре точно так, как указано выше. Некоторые значения содержат пробел, например "windows phone" и "huawei android". "Android" будет отклонено с ошибкой 400 invalid platform name in platforms: 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 сообщения, полученный из Control Panel Pushwoosh
   "campaign_code": "AAAAA-XXXXX",                 // опционально, код кампании для получения лога
   "hwid": "aaazzzqqqqxxx",                        // опционально, HWID конкретного устройства, на которое было отправлено сообщение
   "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", "delivered", "opened", "reject", "create", "inbox_delivered", "inbox_read", "inbox_opened", "inbox_deleted". Ответ будет включать все сообщения с указанным(и) действием(ями).
   "platforms": ["ios", "chrome"],                 // опционально, используется для фильтрации результатов, только в нижнем регистре. Возможные значения: "unknown", "ios", "blackberry", "android", "windows phone", "osx", "windows", "amazon", "safari", "chrome", "firefox", "ie", "email", "fb messenger", "baidu android", "huawei android", "sms", "xiaomi", "web", "whatsapp", "line", "kakao", "telegram", "apple wallet", "google wallet", "viber"
   "message_type": "broadcast"                     // опционально, "all" (по умолчанию), "broadcast" (message_id != 0), или "transactional" (message_id = 0, включает отправки из Customer Journey)
}'

Важно

Требуется одно из следующих полей:
- 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"
  }, {
    "timestamp": "2000-01-25T11:19:30Z",
    "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": "reject",
    "status": "failed",
    "error_reason": "invalid device token",
    "payload": "SOME_PAYLOAD_STRING"
  }]
}

400: Неверный запрос

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

401: Не авторизован

{
  "error": "account not found"
}

500: Внутренняя ошибка сервера

Каждая запись в data также содержит error_reason (строка, заполняется причиной сбоя, когда status равен "failed") и опциональный payload (строка).

Примечание

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

Страница ответа может содержать меньше записей, чем запрошенный limit. Само по себе это не означает, что экспорт завершен.

Пагинация не завершена, пока pagination_token не станет пустым

Продолжайте запрашивать с возвращенным pagination_token до тех пор, пока pagination_token в ответе не станет пустым. Короткая страница не является сигналом для остановки.

Совет

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

Статистика email

linksInteractions

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

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

Заголовки

Имя	Обязательный	Описание
Authorization	Да	Токен доступа API из Control Panel Pushwoosh.

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

Имя	Обязательный	Тип	Описание
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. Например, если ваше письмо содержит ссылки 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: Неверный запрос

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

401: Не авторизован

{
  "error": "account not found"
}

500: Внутренняя ошибка сервера

linksInteractionsDevices

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

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

Заголовки

Имя	Обязательный	Описание
Authorization	Да	Токен доступа API из Control Panel Pushwoosh.

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

Имя	Обязательный	Тип	Описание
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. Например, если ваше письмо содержит ссылки 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: Неверный запрос

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

401: Не авторизован

{
  "error": "account not found"
}

500: Внутренняя ошибка сервера

bouncedEmails

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

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

Авторизация

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

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

Имя параметра	Тип	Описание	Обязательный
application	string	Код приложения Pushwoosh	Да
message_code	string	Код сообщения.	Обязательно, если не указаны date range или campaign
campaign	string	Код кампании.	Обязательно, если не указаны message_code или date range
date_from	string	Начальная дата для данных в формате ГГГГ-ММ-ДДTHH:MM:SS.000Z (стандарт ISO 8601).	Обязательно, если не указаны message_code или campaign
date_to	string	Конечная дата для данных в формате ГГГГ-ММ-ДДTHH: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 "ГГГГ-ММ-ДДTHH:MM:SS.SSSZ"
  "date_to": "2024-07-20T00:00:00.000Z",      // обязательно, если не указаны message_code или campaign.
                                              //          Конечная дата в формате ISO 8601 "ГГГГ-ММ-ДДTHH: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	Дата возврата (формат: ГГГГ-ММ-ДДTHH: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
  }]
}