Перейти к основному содержимому

API отправка пуш-сообщений

HTTP API — программный интерфейс для отправки пуш-сообщений в мобильные приложения

Принцип работы​

API использует REST архитектуру, все запросы и ответы API передаются в кодировке UTF-8, в формате json с обязательным указанием заголовка

Content-Type: application/json

Базовый адрес API — https://pub.pushed.ru

Попробуйте в Swagger

Отправка пуш-сообщений​

Aдрес https://pub.pushed.ru/v2/publish | метод POST

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

  • clientToken - клиентский токен устройства
  • accessToken - токен мобильного приложения (из системы управления Pushed)
  • тело запроса:
{
  "ttl": <time_to_live>,
  "ttd": <time_to_delivery>,
  "payload": "My push",
  "groupId": <group_id>,
  "cascadingSMS": true,
  "cascadingMailRU": false,
  "SMSpayload": {
   "body": null
    },
  "apns": {
    "alert": {
      "title": null,
      "subtitle": null,
      "body": null,
      "launch-image": null,
      "title-loc-key": null,
      "title-loc-args": null,
      "subtitle-loc-key": null,
      "subtitle-loc-args": null,
      "loc-key": null,
      "loc-args": null
    },
    "badge": null,
    "sound": {
      "critical": null,
      "name": null,
      "volume": null
    },
    "thread-id": null,
    "category": null,
    "content-available": 1,
    "mutable-available": null,
    "target-content-id": null,
    "interruption-level": null,
    "relevance-score": null,
    "filter-criteria": null,
    "stale-date": null,
    "timestamp": null,
    "event": null,
    "dismissal-date": null,
    "attributes-type": null
  },
  "hpk": {
    "notificationTitle": "My title",
    "notificationBody": "My body",
    "notificationButtons": [
      {
        "buttonId": "string",
        "buttonName": "string"
      }
    ]
  }
}

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

  • ttl — Время жизни сообщения в секундах (значение по умолчанию 24 часа, необязательное поле)
  • ttd — Время доставки пуша. Если в сервисе включен каскад, например, на СМС, то при неуспешной доставке через время TTD будет отправлена СМС (значение по умолчанию 24 часа, необязательное поле)
  • payload — Тело сообщения (до клиента будет доставлено в том виде, в котором передано, обязательное поле)
  • groupId — Отправить только определенной группе (необязательное поле)
  • cascadingSMS — Включить каскадную отправку через смс
  • cascadingMailRU — Включить каскадную отправку через ВК/одноклассники
  • SMSpayload — текст, который будет отправлен в СМС (payload идет в пуш, а SMSPayload в СМС, если передан только payload, то он отправляется по всем каналам)
  • apns — Настройки для отправки через APNs (необязательное поле)
  • hpk — Настройки для отправки через HPK (необязательное поле)

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

curl -v -X POST https://pub.pushed.ru/v2/publish/<clientToken>
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <accessToken>' 
-d '{"payload": "123"}'

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

{
    "model": {
        "id": "66d5a0bb6a1dc7d467d1adee",
        "createdAt": "2024-09-02T11:25:47.8329958Z",
        "sentAt": null,
        "messageStatus": "InProcess"
    },
    "success": true,
    "message": null,
    "errCode": null
}

Параметры тела ответа​

  • success — результат выполнения запроса, возможные значения true/false
  • errCode — код ошибки, будет заполнено в случае ошибки, возможные значения int/null
  • message — текстовое описание ошибки, будет заполнено в случае ошибки, возможные значения string/null
  • model — данные ответа, будет заполнено в случае успешного выполнения





Трансляция пуш-сообщений (broadcast)​

Aдрес https://pub.pushed.ru/v2/broadcast-publish | метод POST

Тело запроса:

{
  "ttl": <time_to_live>,
  "groupId": <group_id>,
  "payload": "My push",
  "apns": {
    "alert": {
      "title": null,
      "subtitle": null,
      "body": null,
      "launch-image": null,
      "title-loc-key": null,
      "title-loc-args": null,
      "subtitle-loc-key": null,
      "subtitle-loc-args": null,
      "loc-key": null,
      "loc-args": null
    },
    "badge": null,
    "sound": {
      "critical": null,
      "name": null,
      "volume": null
    },
    "thread-id": null,
    "category": null,
    "content-available": 1,
    "mutable-available": null,
    "target-content-id": null,
    "interruption-level": null,
    "relevance-score": null,
    "filter-criteria": null,
    "stale-date": null,
    "timestamp": null,
    "event": null,
    "dismissal-date": null,
    "attributes-type": null
  },
  "hpk": {
    "notificationTitle": "My title",
    "notificationBody": "My body",
    "notificationButtons": [
      {
        "buttonId": "string",
        "buttonName": "string"
      }
    ]
  }
}

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

  • ttl — Время жизни сообщения в секундах (значение по умолчанию 24 часа, необязательное поле)
  • groupId — Идентификатор группы (необязательное поле, если поле не задано, то отправка будет производиться по всем устройствам приложения)
  • payload — Тело сообщения (до клиента будет доставлено в том виде, в котором передано, обязательное поле)
  • apns — Настройки для отправки через APNs (необязательное поле)
  • hpk — Настройки для отправки через HPK (необязательное поле)

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

curl -v -X POST https://pub.pushed.ru/v2/broadcast-publish
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <accessToken>' 
-d '{"payload": "My payload"}'

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

{
    "success": true,
    "errCode": null,
    "message": null
}

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

  • success — результат выполнения запроса, возможные значения true/false
  • errCode — код ошибки, будет заполнено в случае ошибки, возможные значения int/null
  • message — текстовое описание ошибки, будет заполнено в случае ошибки, возможные значения string/null





Подтверждение доставки пуш-сообщений​

Aдрес https://pub.pushed.ru/v2/confirm?transportKind=transportKind | метод POST

Для отправки используется Basic аутентификация, где username - clientToken, а password - messageId

Транспорты​

  • Apns — Apple Push Notification Service
  • Fcm — Firebase Cloud Messaging
  • Hpk — Huawei Push Kit

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

curl -v -X POST https://pub.pushed.ru/v2/confirm?transportKind=Apns
        -H "Authorization: Basic <clientToken:messageId>"

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

{
    "model": {
        "id": "66d5a6586a1dc7d467d1adef",
        "createdAt": "2024-09-02T11:49:44.508Z",
        "sentAt": "2024-09-02T11:49:51.0837854Z",
        "messageStatus": "Delivered"
    },
    "success": true,
    "message": null,
    "errCode": null
}

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

  • success — результат выполнения запроса, возможные значения true/false
  • errCode — код ошибки, будет заполнено в случае ошибки, возможные значения int/null
  • message — текстовое описание ошибки, будет заполнено в случае ошибки, возможные значения string/null
  • model — данные ответа, будет заполнено в случае успешного выполнения





Статус пуш-сообщений​

Aдрес https://pub.pushed.ru/v2/messages | метод POST

Статусы сообщения (messageStatus)​

  • InProcess — новое пуш-сообщение, ожидает отправки,
  • Undelivered — не доставлено,
  • Delivered — доставлено.

Статус по id​

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

  • accessToken - токен мобильного приложения (из системы управления Pushed)
  • id - идентификатор пуш-сообщения

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

curl -v -X POST https://pub.pushed.ru/v2/messages/<messageId>
        -H "Content-Type: application/json"     
        -H "Authorization: Bearer <accessToken>"

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

{
    "model": {
        "id": "66d5a6586a1dc7d467d1adef",               //id пуш-сообщения
        "createdAt": "2024-09-02T11:49:44.508Z",        //дата отправки 
        "sentAt": "2024-09-02T11:49:51.083Z",
        "messageStatus": "Delivered"                    //статус отправки
    },
    "success": true,
    "message": null,
    "errCode": null
}

Статус по clientToken​

Тело запроса:

{
  "clientToken": "string",
  "dateFrom": "2024-08-27T07:43:08.946Z",
  "dateTo": "2024-08-27T07:43:08.946Z",
  "limit": 0,
  "offset": 0
}

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

  • clientToken — Клиентский токен, по котору осуществляется поиск (обязательное поле)
  • dateFrom — Дата в формате UTC, от которой осуществляется поиск (необязательное поле, если параметр не задан выгрузка будет от первого сообщения по клиентскому токену)
  • dateTo — Дата в формате UTC, до которой осуществляется поиск (необязательное поле, если параметр не задан выгрузка будет до последнего сообщения по клиентскому токену)
  • limit — Параметры пагинации. Количество элементов, которое будет возвращено при запросе (необязательное поле, значение по умолчанию - 100)
  • offset — Параметры пагинации. Смещение при поиске сообщений (необязательное поле, значение по умолчанию - 0)

Сообщения будут отсортированы по дате создания

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

curl -v -X POST https://pub.pushed.ru/v2/messages
        -H "Content-Type: application/json"
        -H "Authorization: Bearer <accessToken>"
    -d '{"clientToken":"<clientToken>","dateFrom":"2024-08-27T07:43:08.946Z","dateTo":"2024-08-27T07:43:08.946Z"}'

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

{
    "model": {
        "limit": 100,
        "offset": 0,
        "totalElements": 2,
        "data": [
            {
                "id": "66d5a0bb6a1dc7d467d1adee",
                "createdAt": "2024-09-02T11:25:47.832Z",
                "sentAt": null,
                "messageStatus": "InProcess"
            },
            {
                "id": "66d5a6586a1dc7d467d1adef",
                "createdAt": "2024-09-02T11:49:44.508Z",
                "sentAt": "2024-09-02T11:49:51.083Z",
                "messageStatus": "Delivered"
            }
        ]
    },
    "success": true,
    "message": null,
    "errCode": null
}





Отправка Web пуш-сообщений​

Рекомендуемые ограничения на количество символов

40 символов для заголовка и 80 символов для сообщения

Все уведомления, которые вы отправляете пользователям, отображаются в push-баннере браузера:

web push

Вы можете кастомизировать заголовок, текст, отображаемое изображение, а также URL-адрес, который будет открываться при нажатии на уведомление, отправив следующий запрос через API:

curl --request POST \
  --url https://pub.pushed.ru/v2/publish-web-push/<clientToken> \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Test Notification", // Заголовок //обязательное поле
  "url": "https://pushed.ru/", // Открывается при нажатии //обязательное поле
  "body": "Добрый день", // Текст //обязательное поле
  "image": "https://example.com/image.png" // Изображение // НЕ обязательное поле
  }'

Трансляция веб пуш-сообщений (web broadcast)​

Для отправки веб пуш-сообщений всем подписчикам вашего сайта используйте следующий запрос:

curl --request POST \
  --url https://pub.pushed.ru/v2/publish-broadcast-web-push \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Broadcast Notification", // Заголовок //обязательное поле
  "url": "https://pushed.ru/", // Открывается при нажатии // НЕ обязательное поле
  "body": "Сообщение для всех", // Текст //обязательное поле
  "image": "https://example.com/image.png", // Изображение // НЕ обязательное поле
  "groupid": "66d199c1885e451134479574" // Идентификатор группы // НЕ обязательное поле, если не указано, рассылка осуществляется на все привязанные токены 
  }'

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

{
    "success": true,
    "message": null,
    "errCode": null
}

Параметры тела ответа:

  • success — результат выполнения запроса, возможные значения true/false
  • errCode — код ошибки, будет заполнено в случае ошибки, возможные значения int/null
  • message — текстовое описание ошибки, будет заполнено в случае ошибки, возможные значения string/null