PUSH¶

Отправка¶

Для отправки push-уведомлений необходимо:

Получить ID отправителя и доступ к Push API. Для этого необходимо обратиться в техническую поддержку.
Вызвать POST /push/messages, передавая параметры уведомления в теле запроса и данные авторизации в заголовке.

Примечание

Для автоматической отправки push-уведомлений можно также использовать iOS, Android и Web SDK.

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

Параметр	Тип данных	Описание
from	integer	Согласованный ID отправителя.
to	string	Токен устройства получателя.
title	string	Заголовок уведомления. Максимальная длина - 200 символов.
text	string	Текст уведомления. Максимальная длина - 1024 символа.
priority	string	Приоритет отправки уведомления. `LOW` и `MEDIUM` - низкий и средний приоритеты, используются для рекламных уведомлений. `HIGH` - высокий приоритет, используется для сервисного трафика. `REALTIME` - максимально возможный приоритет, используется для транзакционного трафика. При использовании любого другого значения уведомление будет отклонено.
badge (optional)	integer	Ключ, устанавливающий значение для бейджа приложения - значка с цифрой в верхнем углу иконки приложения. Цифра обозначает количество непрочитанных уведомлений в приложении. Можно задать любое целое число. Чтобы бейдж не отображался, нужно установить значение параметра `0` либо удалить данный параметр.
validity (optional)	integer	Срок жизни уведомления в секундах. Минимальное значение: 30 Максимальное значение: 86400, 1 сутки По умолчанию: 86400, 1 сутки
platform (optional)	string	Платформа или операционная система устройств, на которое будет прислано уведомление. Доступные значения: ○ `IOS` - устройства с ОС iOS. ○ `ANDROID` - устройства с ОС Android. ○ `HUAWEI` - устройства с ОС Huawei.
silentPush (optional)	boolean	Если `true`, уведомление не будет отображаться на устройстве получателя. По умолчанию `false`.
options (optional)	string	Данные, которые будут указаны в коллбэке со статусом уведомления. Любой массив вида `"key"`: `{ "key1": "value1", "key2": "value2" }`
apns (optional)	Apns	Специфические поля для устройств Apple.
android (optional)	Android	Специфические поля для устройств Android и Huawei.

Внимание

Для отправки уведомления необходимо обязательно использовать один из объектов: Apns или Android.

Apns¶

Параметры уведомлений для устройств с ОС iOS.

Параметр	Тип данных	Описание
sound (optional)	string	Звук push-уведомления на iOS. Поддерживает значение `default` или имя файла. Звуковой файл должен входить в основной пакет приложения или в папку `Library`/`Sounds` в контейнере приложения. Поддерживаемые форматы: AIF, AIFF, WAV, MP3, MP4 Максимальный размер: 5 МБ
buttons (optional)	array[ActionButtons]	Включает в себя максимум 3 объекта кнопок.
linkToMedia (optional)	string	URL файла, прикрепляемого к уведомлению. Поддерживаемые форматы: Аудио: AIFF, WAV, MP3, MPEG-4. 5 MB Видео: MPEG, MPEG-2, AVI. 50 MB Изображение: JPEG. PNG, GIF. Разрешение: 1024x1024 или соотношение сторон 1:1, 10 МБ
image (optional)	string	Имя файла изображения в комплекте приложения: с расширением имени файла или без него. Изображение отображается напрямую в уведомлении. Если параметр не указан, система использует изображение с ключом `UILaunchImageFile` в файле `Info.plist` в приложении, или `Default.png`. Поддерживаемые форматы: JPEG, GIF, PNG Размеры: ○ Минимальный - 512х256 ○ Оптимальный - 1440x720 ○ Максимальный - 2880х1440 Разрешение: 1440x720 или соотношение сторон 2:1
action (optional)	string	URL/deep link для перехода при нажатии на уведомление.

Android¶

Параметры уведомлений для устройств с ОС Android и Huawei.

Параметр	Тип данных	Описание
smallIcon (optional)	string	Ссылка на иконку уведомления. Иконка будет отображаться в качестве превью в панели уведомления. Ссылка должна вести на иконку в основном пакете приложения.
iconColor (optional)	string	Цвет иконки уведомлений в формате `#RRGGBB`.
sound (optional)	string	Звук push-уведомления на Android. Поддерживает значение `default` или имя файла звукового ресурса, входящего в состав приложения. Звуковые файлы должны находиться в `/res/raw/`. Поддерживаемые форматы: AIF/AIFF, WAV, MP3, MP4 Максимальный размер: 5 MB
buttons (optional)	array[ActionButtons]	Включает в себя максимум 3 объекта кнопок.
image (optional)	string	Имя файла изображения в комплекте приложения: с расширением имени файла или без него. Изображение отображается напрямую в уведомлении. Если параметр не указан, система использует изображение, идентифицированное ключом `UILaunchImageFile` в файле `Info.plist` приложения, или `Default.png`. Поддерживаемые форматы: JPEG, GIF, PNG Размеры: ○ Минимальный - 512х256 ○ Оптимальный - 1440x720 ○ Максимальный - 2880х1440 Разрешение: 1440x720 или соотношение сторон 2:1
androidChannelId (optional)	string	ID канала уведомления.
tag (optional)	string	ID для отбора пользователей. Используется для тегирования абонентов в базах клиентов в FireBase.
collapseKey (optional)	string	При получении уведомлений с одинаковым `collapseKey`, Firebase Cloud Messaging (FCM) заменяет более старое уведомление на новое.
icon (optional)	string	URL иконки уведомления. Поддерживаются форматы иконок: 24x24, 36x36, 48x48, 72x72, 96x96
action (optional)	string	URL/deep link для перехода при нажатии на уведомление.

ActionButtons¶

Параметр

Тип данных

Описание

icon
(optional)

string

URL иконки уведомления. Используется только для Android.

Поддерживаются форматы иконок: 24x24, 36x36, 48x48, 72x72, 96x96

caption
(optional)

string

Название кнопки. Максимальная длина - 30 символов.

action
(optional)

string

URL/deep link для перехода при нажатии на кнопку в уведомлении.

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

[
  {
    "from":400,
    "to":"r0Fo0EjfqKjTeZZpPW4s63PpMEYpgKIj55DT",
    "title":"title",
    "text":"Hello",
    "badge":1,
    "validity":86400,
    "priority":"MEDIUM",
    "options":{
       "name":"Иван",
       "phone":"79169492211"
    },
    "apns":{
       "linkToMedia":"Default.png",
       "sound":"hi.mp3",
       "action":"https://test.com/apple-app-site-association"
    },
    "android":{
       "icon":"Default.png",
       "iconColor":"#FF4500",
       "sound":"hi.mp3",
       "action":"https://test.com/android-app-site-association"
    }
  }
]

Параметры ответа¶

Параметр	Тип данных	Описание
index	integer	Порядковый номер получателя из массива уведомлений.
pushToken	string	Токен устройства получателя.
pushId	integer	ID уведомления. Указывается только при `"code": "ok"`.
code	string	Указывает на результат обработки уведомления. 1. `ok` - успешно обработано. 2. `validation_error` - ошибка валидации уведомления.
description	array	Массив ошибок, произошедших во время обработки уведомления. Указывается только при `"code": "validation_error"`.
description.errorMessage	string	Сообщение с описанием ошибки.

Примеры ответов¶

OK

{
  "result": [
    {
      "index": 0,
      "pushToken": "IOvpeJ0ECENA3WrrRHG1ghopWkVgiFNLSWWZoqLAUgIllcDF3j19ay9-0-Nanfo-0VjrnA1G6CGSvE_TyRUaea7mXmDUapY3YA",
      "pushId": 3703545281276230700,
      "code": "ok"
    }
  ]
}

VALIDATION ERROR

{
  "result": [
    {
      "index": 0,
      "pushToken": "IOvpeJ0ECENA3WrrRHG1ghopWkVgiFNLSWWZoqLAUgIllcDF3j19ay9-0-Nanfo-0VjrnA1G6CGSvE_TyRUaea7mXmDUapY3YA",
      "code": "validation_error",
      "description": [
        {
          "errorMessage": "Неизвестный from"
        }
      ]
    }
  ]
}

Коллбэки¶

Как подключить

Для настройки коллбэков со статусами push-уведомлений необходимо обратиться к менеджеру компании или в техническую поддержку.

Возможные статусы¶

Статус	Описание
accepted	Уведомление было принято на доставку.
send	Уведомление отправлено в службу уведомлений устройства.
delivered	Уведомление доставлено до устройства.
opened	Был переход по ссылке из уведомления.
rejected	Уведомление отклонено.
canceled	Получатель смахнул уведомление с экрана.
expired	Уведомление не было доставлено за отведенное время.
unsubscribed	Пользователь отключил уведомления.

Пример коллбэка¶

[
    {
        "messageId": 1,
        "ts": 1636976602504,
        "status": "delivered",
        "errorCode": 0,
        "options": "string"
    }
]

Детализация¶

Для получения детальных сведений об отправленных уведомлениях необходимо вызвать GET /push-statistics/statistics/detail, передавая параметры фильтров и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
limit	integer	Количество уведомлений в результатах поиска.
offset	integer	Смещение результатов поиска. То есть, к примеру, если в параметре будет указано число `5`, полученный массив уведомлений будет отображаться, начиная с 5 позиции.
taskId (optional)	integer	ID рассылки, по которой нужно получить детализацию. Можно узнать при создании сценария рассылки. Используется в обязательной комбинации параметров.
triggerId (optional)	integer	ID триггера рассылки. Можно узнать при получении сценария рассылки. Используется в обязательной комбинации параметров.
dateTimeFrom (optional)	datetime	Дата начала поиска уведомлений. Используется в обязательной комбинации параметров. Формат `YYYY-MM-DD+hh:mm:ss`.
dateTimeTo (optional)	datetime	Дата окончания поиска уведомлений. Используется в обязательной комбинации параметров. Формат `YYYY-MM-DD+hh:mm:ss`.
messageIds (optional)	array[integer]	ID уведомлений, по которым нужно получить детализацию. Используется в обязательной комбинации параметров.
applicationId (optional)	integer	ID приложения в Devino.Online, откуда отправляются push-уведомления.
order (optional)	string	В каком порядке выводить результаты запроса. Возможные значения: ○ `ASC` - в возрастающем порядке. ○ `DESC` - в убывающем порядке.
selectionField (optional)	string	Поле, по которому будут отсортированы результаты запроса.
outFields (optional)	array[string]	Поля в результатах поиска. Неуказанные в этом параметре поля будут исключены.
recipient (optional)	string	Номер телефона получателя.
status (optional)	string	Статус уведомлений в результатах поиска. Возможные значения: ○ `DELIVERED` - уведомление доставлено получателю. ○ `IN_PROGRESS` - уведомление находится в процессе отправки. ○ `READ` - уведомление было прочитано получателем. ○ `CANCELED` - получатель смахнул уведомление с экрана. ○ `REJECTED` - уведомление было отклонено оператором или Devino.Online. ○ `UNDELIVERED` - уведомление не доставлено.
timeOffset (optional)	integer	Часовой пояс получателя. Формат - смещение в минутах, например, `180` для Москвы (GMT+3).
userId (optional)	integer	ID пользователя, проводившего рассылку.

Комбинации параметров¶

Для корректной работы метода в запросе необходимо использовать одну из этих комбинаций параметров в соответствии со списком:

ID рассылки: taskId
ID рассылки и триггера: taskId, triggerId
Даты начала и окончания поиска уведомлений: dateTimeFrom, dateTimeTo
ID рассылки, триггера; даты начала и окончания поиска уведомлений: taskId, triggerId, dateTimeFrom, dateTimeTo
ID уведомлений: messageIds

Поля для параметров `selectionField` и `outFields`¶

Используются в параметрах selectionField для сортировки результатов поиска и outFields для фильтрации полей.

Название поля	Описание
APPLICATION_ID	ID приложения в Devino.Online, откуда отправляются push-уведомления.
APPLICATION_NAME	Название приложения.
BODY	Текст push-уведомления.
BUTTONS	Информация о кнопках (объект ActionButtons) в push-уведомлении.
COMPANY_ID	ID компании.
COMPANY_NAME	Название компании.
CUSTOM_DATA	Значение параметра `options` при отправке уведомления.
DEEP_LINK	URL/deep link для перехода при нажатии на уведомление.
EVENT_DATE_TIME	Дата и время последнего обновления статуса уведомления.
MEDIA_FILE	URL изображения, прикрепленного к уведомлению. В ответе на запрос обозначен как параметр `image`.
MESSAGE_ID	ID уведомления.
PRICE	Стоимость уведомления.
RECIPIENT	Push-токен получателя.
SEND_ROUTE	Маршрут, по которому было отправлено уведомление.
SENT_DATE_TIME	Дата и время отправки.
STATUS	Статус уведомления из личного кабинета Devino.Online.
STATUS_DETAILS	Статус уведомления из базы данных.
TASK_ID	ID рассылки.
TASK_NAME	Название рассылки.
TASK_TYPE	Тип рассылки.
TITLE	Заголовок push-уведомления.
TRIGGER_CONTACT_GROUP	Название списка контактов, по которому проходила рассылка. В ответе на запрос будет обозначен как параметр `list`.
TRIGGER_SEGMENT	Название сегмента списка контактов, по которому проходила рассылка. В ответе на запрос обозначен как параметр `segment`.
TRIGGER_ID	ID триггера рассылки.
USER_ID	ID пользователя, отправившего уведомление.
USER_LOGIN	Логин пользователя, отправившего уведомление.

Примеры запросов¶

С датами

curl -X GET https://api.devino.online/push-statistics/statistics/detail?dateTimeFrom=2023-02-12+00:00:00&dateTimeTo=2023-02-24+00:00:00&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

С ID рассылки и триггера

curl -X GET https://api.devino.online/push-statistics/statistics/detail?taskId=8742&triggerId=2312&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Параметры ответа¶

Параметр	Тип данных	Описание
data	array[object]	Массив объектов с детальной информацией по каждому уведомлению. Параметры определяются полями, которые были заданы в изначальном запросе. Также появляются дополнительные параметры.
size	integer	Количество элементов на странице и уведомлений в результатах поиска. Задается параметром `limit`.
offset	integer	Смещение результатов поиска. То есть, к примеру, если в параметре будет указано число `5`, полученный массив уведомлений будет отображаться, начиная с 5 позиции.
number	integer	Номер полученной страницы. Определяется параметром `offset`. ○ Если значение параметра `offset` будет `0` при любом значении параметра `limit`, то номер полученной страницы будет `1`. ○ Если `offset` будет больше `0`, но меньше, чем значение параметра `limit`, номер страницы будет `2`. Например, при `"offset": 5` и `"limit": 10`, значение параметра `number` будет `2`. ○ Если `offset` будет больше чем `limit`, то номер страницы будет определяться целочисленным делением `offset` на `limit` плюс 1 (`offset` / `limit` + 1). Например, при `"offset": 1000` и `"limit": 50`, значение параметра `number` будет `21` (`1000` / `50` + 1 = `21`).
pageExists	boolean	Существует ли отображаемая страница.
total	integer	Общее количество уведомлений, по которым можно получить детализацию.
pages	integer	Общее количество страниц, по которым можно получить детализацию. Определяется целочисленным делением параметра `total` на `limit` (`total` / `limit`).
more	boolean	Индикатор: существуют ли страницы после текущей, указанной в параметре `number`.

Data¶

Параметр Тип данных Описание

recipientPlatform

string

Платформа или операционная система устройства, на которое было прислано уведомление.

Доступные значения:
○ APNS - устройства с ОС iOS.
○ FIREBASE - устройства с ОС Android.
○ HUAWEI - устройства с ОС Huawei.

isListDeleted boolean Удален ли список контактов, контакту которого было отправлено уведомление.

isSegmentDeleted boolean Удален ли сегмент списка контактов, контакту которого было отправлено уведомление.

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

{
  "result": {
    "offset": 1000,
    "number": 21,
    "size": 50,
    "pageExists": true,
    "data": [
      {
        "messageId": "234567865432456787634",
        "applicationId": 111,
        "applicationName": "App",
        "taskId": "11111",
        "taskName": "task",
        "taskType": "SIMPLE",
        "triggerId": "11111111",
        "list": "Contact_list",
        "isListDeleted": false,
        "segment": "Segment",
        "isSegmentDeleted": false,
        "recipient": "71110000999:APA91bFdDBjCi_6sePNogM3eJ...",
        "sentDateTime": "2022-12-14 05:55:32",
        "status": "UNDELIVERED",
        "statusDetails": "REJECTED",
        "eventDateTime": "2022-12-14 05:54:52",
        "companyId": 234,
        "companyName": "MyCompany",
        "userId": 88,
        "userLogin": "79991112233",
        "price": "1.0000",
        "body": "Notification text",
        "title": "Notification title",
        "recipientPlatform": "FIREBASE",
        "image": "https://devinotele.com/media.jpg",
        "deepLink": "http://devinotele.com",
        "actionButtons": [
          {
            "buttonName": "PUSH ME 1",
            "buttonUrl": "1"
          },
          {
            "buttonName": "PUSH ME 2",
            "buttonUrl": "2"
          },
          {
            "buttonName": "PUSH ME 3",
            "buttonUrl": "3"
          }
        ],
        "customData": {
          "OMNI": {
            "contactId": "21dfswarfsg3423ede2",
            "triggerId": 11111111,
            "taskId": 11111
          }
        }
      },
      ...
    ],
    "more": true,
    "pages": 100,
    "total": 1000
  }
}

Статистика уведомлений¶

Для получения общей статистики по статусам уведомлений необходимо вызвать GET /push-statistics/statistics/of-group, передавая параметры фильтров и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
groupBy	string	Группировка результатов: ○ `NONE` - без группировки ○ `YEAR` - по годам ○ `MONTH` - по месяцам ○ `WEEK` - по неделям ○ `DAY` - по дням ○ `HOUR` - по часам
startDate	datetime	Дата начала периода сбора статистики. Формат - `YYYY-MM-DDThh%3Amm%3Ass`.
endDate	datetime	Дата окончания периода сбора статистики. Формат - `YYYY-MM-DDThh%3Amm%3Ass`.
taskId (optional)	integer	ID рассылки, по которой нужно получить статистику.
triggerId (optional)	integer	ID триггера рассылки, по которому нужно получить статистику.
timeOffset (optional)	integer	Часовой пояс получателя. Формат - смещение в минутах, например, `180` для Москвы (GMT +3).

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

curl -X GET https://api.devino.online/push-statitics/statistics/of-group?startDate=2022-10-06T13%3A45%3A30&endDate=2023-02-06T13%3A45%3A30&groupBy=MONTH
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Параметры ответа¶

Параметр	Тип данных	Описание
messages	array[MessageStatusObject]	Количество уведомлений по выбранному периоду, сгруппированных по статусам.

MessageStatusObject¶

Объект содержит информацию о количестве уведомлений со статусами:

Код	Описание
accepted	Уведомление было принято на доставку.
send	Уведомление отправлено в службу уведомлений устройства.
delivered	Уведомление доставлено до устройства.
opened	Был переход по ссылке из уведомления.
rejected	Уведомление отклонено.
canceled	Получатель смахнул уведомление с экрана.
expired	Уведомление не было доставлено за отведенное время.
unsubscribed	Пользователь отключил уведомления.

Каждый статус включает в себя параметры:

Параметр	Тип данных	Описание
date	string	Дата сбора статистики в зависимости от значения параметра `groupBy`.
amount	integer	Количество уведомлений.

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

{
  "result": {
    "messages": {
      "accepted": [],
      "send": [
        {
          "date": "2022-09-01 00:00:00",
          "amount": 11
        },
        {
          "date": "2022-10-01 00:00:00",
          "amount": 24
        },
        {
          "date": "2023-01-01 00:00:00",
          "amount": 2
        }
      ],
      "delivered": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 2
        }
      ],
      "opened": [
        {
          "date": "2022-10-01 00:00:00",
          "amount": 49
        },
        {
          "date": "2022-09-01 00:00:00",
          "amount": 23
        },
        {
          "date": "2022-11-01 00:00:00",
          "amount": 1
        }
      ],
      "rejected": [],
      "canceled": [],
      "expired": [],
      "unsubscribed": []
    }
  }
}

PUSH¶

Отправка¶

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

Apns¶

Android¶

ActionButtons¶

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

Параметры ответа¶

Примеры ответов¶

Коллбэки¶

Возможные статусы¶

Пример коллбэка¶

Детализация¶

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

Комбинации параметров¶

Поля для параметров selectionField и outFields¶

Примеры запросов¶

Параметры ответа¶

Data¶

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

Статистика уведомлений¶

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

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

Параметры ответа¶

MessageStatusObject¶

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

Поля для параметров `selectionField` и `outFields`¶