Device API

registerDevice

POST https://api.pushwoosh.com/json/1.3/registerDevice

Вызывается внутренне из SDK. Регистрирует устройство для приложения.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен Device API для доступа к Device API. Замените XXXX вашим фактическим токеном Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
push_token	string	Push-токен для устройства.
language	string	Языковая локаль устройства. Должна быть двухбуквенным кодом в нижнем регистре в соответствии со стандартом ISO-639-1.
hwid*	string	Уникальная строка для идентификации устройства (IDFV на iOS, случайно сгенерированное значение на Android). Узнать больше
timezone	integer	Смещение часового пояса в секундах для устройства.
device_type*	integer	Тип устройства. Возможные значения см. ниже.
email	string	Адрес электронной почты для регистрации (используйте для email-пользователей вместо HWID и push-токена).
tags	object	Значения тегов для присвоения зарегистрированному устройству.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Пример

{
  "request": {
    "application": "XXXXX-XXXXX",        // обязательно. Код приложения Pushwoosh
    "push_token": "dec301908b9ba8XXXXX57a58e40f96f5XXXXX2068674f5XXXXa25cdc250a2a41", // опционально.
    "hwid": "1CA6XXXXX-8DAC-XXXXX-XXXXX-B756288B6D3C",                                   // обязательно. Аппаратный ID устройства
    "idfa": "AEBE52E7-0XXXXX-455A-XXXXX-E57283966239",                                   // опционально.
    "timezone": 3600,                    // опционально. Смещение в секундах
    "device_type": 1,                    // обязательно. Возможные значения см. ниже. Для email,
                                         //           используйте параметры "emails", как описано ниже.
    "email": "email_address@domain.com", // используйте вместо "hwid" и "push_token" для регистрации
                                         //           адреса электронной почты для вашего email-проекта
    "language": "en",                    // опционально. Код языка ISO 639-1|639-2
    "userId": "Alex",                    // опционально.
    "tags": {                            // опционально. Значения тегов для установки на зарегистрированном устройстве
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"], // устанавливает список значений для тегов типа List
      "DateTag": "2024-10-02 22:11",     // обратите внимание, что время должно быть в UTC
      "BooleanTag": true                 // допустимые значения: true, false
    },

    // системные теги, опционально
    "app_version": "1.2.3",
    "device_model": "Samsung SM-G355H",
    "os_version": "2.3",

    // опциональные ключи шифрования для chrome/firefox
    "public_key": "BNmDO4BTKEMJqaqprTf7t/HBXXXXX/orcXXXXX/scS5CFP6XXXXXHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
    "auth_token": "RlRmCXXXXX/s7XXXXXjKFzoQ==",

    // опциональные ключи FCM для Chrome (для XMPP)
    "fcm_token": "BNmDO4BTKEMJXXXXXprTf7t/XXXXXBQ/orXXXXXc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
    "fcm_push_set": "RlXXXXXGM/s7XXXXXjKFzoQ=="
  }
}

Возможные типы устройств:

• 1 – iOS
• 3 – Android
• 7 – Mac OS X
• 8 – Windows
• 9 – Amazon
• 10 – Safari
• 11 – Chrome
• 12 – Firefox
• 14 – Email
• 17 – Huawei
• 18 – SMS
• 21 – WhatsApp

Регистрация email-устройств

Чтобы зарегистрировать email-подписчика для вашего приложения, отправьте параметр "email": "email_address@domain.com" в вашем запросе /registerDevice или /registerEmail следующим образом:

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

{
  "request":{
    "application": "XXXXX-XXXXX",        // обязательно. Код приложения Pushwoosh
    "email": "email_address@domain.com", // обязательно. Адрес электронной почты для регистрации в вашем email-проекте
    "language": "en",                    // опционально. Код языка ISO 639-1|639-2
    "userId": "Alex",                    // опционально.
    "tags": {                            // опционально. Значения тегов для установки на зарегистрированном устройстве
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"], // устанавливает список значений для тегов типа List
      "DateTag": "2024-10-02 22:11",     // обратите внимание, что время должно быть в UTC
      "BooleanTag": true                 // допустимые значения: true, false
    }
  }
}

Регистрация WhatsApp-устройств

Чтобы зарегистрировать WhatsApp-устройство для вашего приложения, следуйте этим рекомендациям:

• hwid: Убедитесь, что это поле содержит префикс whatsapp: за которым следует номер телефона в формате E.164 (например, whatsapp:+0000000000). Номер телефона должен быть действительным, что будет проверено Pushwoosh.

• Push-токен: Push-токен не требуется, так как hwid будет автоматически функционировать как push-токен.

• device_type: Установите значение этого поля равным 21, чтобы указать WhatsApp в качестве платформы.

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

{
  "request": {
    "application": "XXXXX-XXXXX",        // обязательно. Код приложения Pushwoosh
    "hwid": "whatsapp:+0000000000",      // обязательно. Префикс WhatsApp и действительный номер телефона
    "timezone": 3600,                    // опционально. Смещение времени в секундах
    "device_type": 21,                   // обязательно. Тип устройства WhatsApp — 21
    "language": "en",                    // опционально. Код языка ISO 639-1|639-2
    "userId": "Alex",                    // опционально. Идентификатор пользователя
    "tags": {                            // опционально. Значения тегов для пользовательской сегментации
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",     // формат UTC
      "BooleanTag": true
    },
    "app_version": "1.2.3",              // опционально. Версия приложения
    "device_model": "Samsung SM-G355H",  // опционально. Модель устройства
    "os_version": "2.3"                  // опционально. Версия операционной системы
  }
}

Регистрация SMS-устройств

Чтобы зарегистрировать SMS-устройство для вашего приложения, следуйте этим рекомендациям:

• hwid: Убедитесь, что это поле содержит номер телефона в формате E.164 (например, +0000000000). Номер телефона должен быть действительным, что будет проверено Pushwoosh.

• Push-токен: Push-токен не требуется, так как hwid будет автоматически функционировать как push-токен.

• device_type: Установите значение этого обязательного поля равным 18, чтобы указать SMS в качестве платформы.

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

{
   "request": {
      "application": "XXXXX-XXXXX",           // обязательно. Код приложения Pushwoosh
      "hwid": "+0000000000",                  // обязательно. Действительный номер телефона в формате E.164
      "timezone": 3600,                       // опционально. Смещение времени в секундах
      "device_type": 18,                      // обязательно. Тип устройства SMS — 18
      "language": "en",                       // опционально. Код языка ISO 639-1|639-2
      "userId": "Alex",                       // опционально. Идентификатор пользователя
      "tags": {                               // опционально. Значения тегов для пользовательской сегментации
           "StringTag": "string value",
           "IntegerTag": 42,
           "ListTag": ["string1", "string2"],
           "DateTag": "2024-10-02 22:11",     // формат UTC
           "BooleanTag": true
      },
      "app_version": "1.2.3",                 // опционально. Версия приложения
      "device_model": "Samsung SM-G355H",     // опционально. Модель устройства
      "os_version": "2.3"                     // опционально. Версия операционной системы
   }
}

Коды состояния:

Код состояния HTTP	status_code	Описание
200	200	Устройство успешно зарегистрировано
200	210	Ошибка аргумента. См. status_message для получения дополнительной информации.
400	N/A	Неверно сформированная строка запроса
500	500	Внутренняя ошибка

unregisterDevice

POST https://api.pushwoosh.com/json/1.3/unregisterDevice

Удаляет push-токен устройства. Отмененное устройство по-прежнему учитывается в общем количестве устройств (Total Devices) и может быть доступно для In-App сообщений. Вызывается внутренне из SDK.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен Device API для доступа к Device API. Замените XXXX вашим фактическим токеном Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, использованный в запросе /registerDevice.

200

{
    "status_code": 200,
    "status_message": "OK",
    "response": null
}

Пример

{
  "request": {
    "application": "XXXXX-XXXXX",              // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16XXXXXe7a6beceXXXXX530fb2"  // обязательно. Аппаратный ID устройства, использованный в /registerDevice API
  }
}

Примечание

Для email вызовите /deleteEmail.

Коды состояния:

Код состояния HTTP	status_code	Описание
200	200	Устройство успешно отписано
200	210	Ошибка аргумента. См. status_message для получения дополнительной информации.
400	N/A	Неверно сформированная строка запроса
500	500	Внутренняя ошибка

deleteDevice

POST https://api.pushwoosh.com/api/v2/device-api/deleteDevice

Удаляет устройство и все связанные с ним данные, идентифицированные по указанному HWID в приложении. В отличие от /unregisterDevice, который только удаляет push-токен и сохраняет запись об устройстве, /deleteDevice полностью удаляет устройство. Запрос обрабатывается асинхронно, и конечная точка возвращает 200 OK, как только запрос на удаление будет принят к обработке.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен Device API для доступа к Device API. Замените XXXX вашим фактическим токеном Device API.
Content-Type	Да	application/json

Тело запроса

Имя	Обязательный	Тип	Описание
application	Да	string	Код приложения Pushwoosh
hwid	Да	string	Аппаратный ID устройства устройства для удаления.

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

{
  "application": "XXXXX-XXXXX",                 // обязательно. Код приложения Pushwoosh
  "hwid": "8f65b16df378e7a6bece9614e1530fb2"    // обязательно. Аппаратный ID устройства для удаления
}

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

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Коды состояния

Код состояния HTTP	status_code	Описание
200	200	Запрос на удаление принят
200	210	Ошибка аргумента. См. status_message для получения дополнительной информации.
400	N/A	Неверно сформированная строка запроса
401	N/A	Отсутствует или недействителен токен авторизации
500	500	Внутренняя ошибка

setTags

POST https://api.pushwoosh.com/json/1.3/setTags

Устанавливает значения тегов для устройства. Вызывается из SDK.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен Device API для доступа к Device API. Замените XXXX вашим фактическим токеном Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, использованный в запросе /registerDevice.
tags*	object	JSON-объект устанавливаемых тегов, отправьте “null” для удаления значения.

200

{
   "status_code": 200,
   "status_message": "OK",
   "response": null
}

Примечание

Метод вызывается из SDK. Его можно вызывать удаленно с вашего бэкенда, однако вам необходимо поддерживать актуальную базу данных hwid на стороне бэкенда.

Пример

{
  "request":{
    "application": "XXXXX-XXXXX",               // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16XXXXXe7a6becXXXXXe1530fb2", // обязательно. Аппаратный ID устройства, использованный в /registerDevice API
    "tags": {                                   // обязательно.
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],        // устанавливает список значений для тегов типа List
      "DateTag": "2024-10-02 22:11",            // обратите внимание, что время в UTC
      "BooleanTag": true                        // допустимые значения - true, false
    }
  }
}

Инкремент значений тега Integer

Чтобы увеличить значение тега Integer, используйте параметр operation со значением “increment” следующим образом:

{
  "request":{
    "application": "12345-67890",                   // обязательно. Код приложения Pushwoosh
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // обязательно. Аппаратный ID устройства, использованный в /registerDevice API
    "tags": {                                       // обязательно.
      "Level": {                                    // Имя тега
        "operation": "increment",                   // перезаписывает целочисленный тег с шагом следующего значения
        "value": 1                                  // инкремент для значения тега
      }
    }
  }
}

Декремент значений тега Integer

Для уменьшения используйте отрицательные числа в качестве значения для операции “increment” (-1, -2, -3, -n):

{
  "request":{
    "application": "12345-67890",                   // обязательно. Код приложения Pushwoosh
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // обязательно. Аппаратный ID устройства, использованный в /registerDevice API
    "tags": {                                       // обязательно
      "Level": {                                    // Имя тега
        "operation": "increment",                   // перезаписывает целочисленный тег с уменьшением на следующее значение
        "value": -1                                 // декремент для значения тега
      }
    }
  }
}

Добавление значений в тег List

Чтобы расширить тег List новыми значениями, используйте параметр operation со значением “append” следующим образом:

Пример

{
  "request": {
    "hwid": "3d124a79XXXXf189XXXX7dfd9XXXXafd", // обязательно. Аппаратный ID устройства, использованный в /registerDevice API
    "application": "6XXXX-XXXX3",               // обязательно. Код приложения Pushwoosh
    "tags": {                                   // обязательно.
      "ListTag": {                              // Имя тега
        "operation": "append",                  // добавляет следующие значения в список значений тега
        "value": [                              // значения для добавления
          "tag2",
          "tag3"
        ]
      }
    }
  }
}

Удаление значений из тега List

Чтобы удалить некоторые значения из тега List, используйте операцию “remove” следующим образом:

{
  "request":{
    "application": "12345-67890",                   // обязательно. Код приложения Pushwoosh
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // обязательно. Аппаратный ID устройства, использованный в /registerDevice API
    "tags": {                                       // обязательно.
      "In-App Product": {                           // Имя тега
        "operation": "remove",                      // удаляет следующие значения из тега списка
        "value": "outwear_02"                       // значение или значения для удаления
      }
    }
  }
}

Установка тегов по UserID

Чтобы установить теги для всех устройств, связанных с определенным User ID, используйте параметр “userId” вместо “hwid”.

Осторожно

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

Пример

{
  "request":{
    "application": "AAAAA-BBBBB", // Код приложения Pushwoosh
    "userId": "some_user",        // User ID, для которого вы хотите установить теги
    "tags": {                     // теги и значения для установки
      "Language": "es"
    }
  }
}

Примечание

Для email вызовите /setEmailTags.

Коды состояния:

Код состояния HTTP	status_code	Описание
200	200	Теги успешно установлены
200	210	Ошибка аргумента. См. status_message для получения дополнительной информации.
400	N/A	Неверно сформированная строка запроса
500	500	Внутренняя ошибка

getTags

POST https://api.pushwoosh.com/json/1.3/getTags

Получает список тегов с соответствующими значениями для конкретного устройства.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен Device API для доступа к Device API. Замените XXXX вашим фактическим токеном Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
userId	string	User ID для использования вместо “hwid”. Если используется вместе с “hwid”, “hwid” имеет приоритет.
hwid	string	Аппаратный ID устройства, использованный в запросе /registerDevice.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "result": {
      "Language": "fr"
    }
  }
}

Пример

{
  "request":{
    "application": "XXXXX-XXXXX",   // обязательно. Код приложения Pushwoosh
    "hwid": "HWID",                 // опционально. Аппаратный ID устройства, использованный в /registerDevice API
    "userId": "USER_ID"             // опционально. Может использоваться вместо "hwid" для получения тегов для конкретного пользователя
  }
}

setBadge

POST https://api.pushwoosh.com/json/1.3/setBadge

Отправляет текущее значение значка (badge) для устройства в Pushwoosh. Вызывается внутренне из SDK.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен Device API для доступа к Device API. Замените XXXX вашим фактическим токеном Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, использованный в запросе /registerDevice.
badge*	integer	Текущий значок в приложении.

200

{
  "status_code": 200,
  "status_message": "OK"
}

Пример

{
  "request":{
    "application": "XXXXX-XXXXX",               // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16dXXXXe7a6XXXX9614XXXX0fb2", // обязательно. Аппаратный ID устройства, использованный в /registerDevice API
    "badge": 4                                  // обязательно. Текущий значок в приложении
  }
}

Вызывается из SDK внутренне. Отправляет текущее значение значка для устройства в Pushwoosh. Это происходит внутренне, когда приложение изменяет значение значка на устройстве iOS. Позволяет правильно работать автоинкрементируемым значкам.

Осторожно

Этот метод НЕ используется для обновления значения значка на устройстве. Вместо этого используйте запрос /createMessage с параметром "ios_badges".

applicationOpen

POST https://api.pushwoosh.com/json/1.3/applicationOpen

Регистрирует событие открытия приложения. Вызывается внутренне из SDK.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен Device API для доступа к Device API. Замените XXXX вашим фактическим токеном Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, использованный в запросе /registerDevice.

200

{
  "status_code": 200,
  "status_message": "OK"
}

Пример

{
  "request": {
    "application": "XXXXX-XXXXX",              // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16dXXXXe7a6XXXX9614eXXXXfb2" // обязательно. Аппаратный ID устройства, использованный в /registerDevice API
  }
}

pushStat

POST https://api.pushwoosh.com/json/1.3/pushStat

Регистрирует событие открытия push-уведомления. Вызывается внутренне из SDK.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен Device API для доступа к Device API. Замените XXXX вашим фактическим токеном Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, использованный в запросе /registerDevice.
userId	string	User ID для связи с событием открытия push-уведомления.
hash	string	Хэш-тег, полученный в push-уведомлении (параметр “p” в полезной нагрузке push-уведомления).

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Пример

{
  "request": {
    "application": "XXXXX-XXXXX",               // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16dfXXXX7a6beXXXX14e1530fb2", // обязательно. Аппаратный ID устройства, использованный в /registerDevice API
    "userId": "USER012345",                     // опционально. User ID для связи с событием открытия push-уведомления
    "hash": "HASH_TAG"                          // опционально. Хэш-тег, полученный в push-уведомлении
                                                //           (параметр "p" в полезной нагрузке push-уведомления)
  }
}

messageDeliveryEvent

POST https://api.pushwoosh.com/json/1.3/messageDeliveryEvent

Регистрирует событие доставки push-уведомления для устройства. Вызывается внутренне из SDK.

Заголовки запроса

Имя	Обязательный	Значение	Описание
Authorization	Да	Token XXXX	Токен Device API для доступа к Device API. Замените XXXX вашим фактическим токеном Device API.

Тело запроса

Имя	Тип	Описание
application*	string	Код приложения Pushwoosh
hwid*	string	Аппаратный ID устройства, использованный в запросе /registerDevice.
hash	string	Хэш-тег, полученный в push-уведомлении (параметр “p” в полезной нагрузке push-уведомления).

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Пример

 {
  "request": {
    "application": "XXXXX-XXXXX",               // обязательно. Код приложения Pushwoosh
    "hwid": "8f65b16dfXXXX7a6bece9XXXX1530fb2", // обязательно. Аппаратный ID устройства, использованный в /registerDevice API
    "hash": "HASH_TAG"                          // опционально. Хэш-тег, полученный в push-уведомлении
                                                //           (параметр "p" в полезной нагрузке push-уведомления)
  }
}