Device API

post
/registerDevice

https://cp.pushwoosh.com/json/1.3/registerDevice
Called internally from the SDK. Registers device for the application.
Request
Response
Body Parameters
application
required
string
Pushwoosh application code.
push_token
required
string
Push token for the device.
language
optional
string
Language locale of the device. Must be a lowercase two-letter code according to ISO-639-1 standard.
hwid
required
string
Unique string to identify the device (IDFV on iOS, randomly generated value on Android).
timezone
optional
integer
Timezone offset in seconds for the device.
device_type
required
integer
Device type. See possible values below.
200: OK
{
"status_code":200,
"status_message":"OK",
"response": null
}
Example
{
"request":{
"application": "XXXXX-XXXXX", // Pushwoosh application code
"push_token": "dec301908b9ba8df85e57a58e40f96f523f4c2068674f5fe2ba25cdc250a2a41",
"hwid": "1CA68A12-8DAC-4BB7-BEE5-B756288B6D3C", // hardware device ID
"idfa" : "AEBE52E7-03EE-455A-B3C4-E57283966239", // optional
"timezone": 3600, // offset in seconds
"device_type": 1,
"language": "en", // ISO 639-1|639-2 language code
"userId": "Alex", // optional
// system tags, optionals
"app_version": "1.2.3",
"device_model": "Samsung SM-G355H",
"jailbroken": "1", // 1 or 0
"os_version": "2.3",
// optional encryption keys for chrome/firefox
"public_key": "BNmDO4BTKEMJqaqprTf7t/HBUd2BQ/orc88cc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
"auth_token": "RlRmCCdGM/s7ouuhjKFzoQ==",
//optional FCM keys for Chrome (for XMPP)
"fcm_token": "BNmDO4BTKEMJqaqprTf7t/HBUd2BQ/orc88cc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
"fcm_push_set": "RlRmCCdGM/s7ouuhjKFzoQ=="
}
}

Possible device types:

  • 1 – iOS

  • 2 – BB

  • 3 – Android

  • 5 – Windows Phone

  • 7 – OS X

  • 8 – Windows 8

  • 9 – Amazon

  • 10 – Safari

  • 11 – Chrome

  • 12 – Firefox

For emails call /registerEmail.

Status codes:

HTTP Status code

status_code

Description

200

200

Device successfully registered

200

210

Argument error. See status_message for more info.

400

N/A

Malformed request string

500

500

Internal error

PHP
<?php
//see http://gomoob.github.io/php-pushwoosh/register-device.html
use Gomoob\Pushwoosh\Model\Request\RegisterDeviceRequest;
// creates request instance
$request = RegisterDeviceRequest::create()
->setDeviceType(DeviceType::1())
->setHwid('HWID')
->setLanguage('fr')
->setPushToken('xxxxxxxx')
->setTimezone(3600);
// call '/registerDevice' Web Service
$response = $pushwoosh->registerDevice($request);
if($response->isOk()) {
print 'Ok, operation successful.';
} else {
print 'Oups, the operation failed :-(';
print 'Status code : ' . $response->getStatusCode();
print 'Status message : ' . $response->getStatusMessage();
}

post
/unregisterDevice

https://cp.pushwoosh.com/json/1.3/unregisterDevice
Removes device from the application. Called internally from the SDK.
Request
Response
Body Parameters
application
required
string
Pushwoosh application code.
hwid
required
string
Hardware device ID used in /registerDevice request.
200: OK
{
"status_code": 200,
"status_message": "OK",
"response": null
}
Example
{
"request":{
"application": "XXXXX-XXXXX", // Pushwoosh application code
"hwid": "8f65b16df378e7a6bece9614e1530fb2" // hardware device ID used in /registerDevice function call
}
}

For emails call /deleteEmail.

Status codes:

HTTP Status code

status_code

Description

200

200

Device successfully unsubscribed

200

210

Argument error. See status_message for more info.

400

N/A

Malformed request string

500

500

Internal error

PHP
<?php
// see http://gomoob.github.io/php-pushwoosh/unregister-device.html
use Gomoob\Pushwoosh\Model\Request\UnregisterDeviceRequest;
// creates request instance
$request = UnregisterDeviceRequest::create()->setHwid('HWID');
// call '/unregisterDevice' Web Service
$response = $pushwoosh->unregisterDevice($request);
if($response->isOk()) {
print 'Ok, operation successful.';
} else {
print 'Oups, the operation failed :-(';
print 'Status code : ' . $response->getStatusCode();
print 'Status message : ' . $response->getStatusMessage();
}

post
/checkDevice

https://cp.pushwoosh.com/json/1.3/checkDevice
Checks whether the device exists on a server.
Request
Response
Body Parameters
application
required
string
Pushwoosh application code.
hwid
required
string
Hardware device ID.
200: OK
{
"status_code": "200",
"status_message": "OK",
"response": {
"exist" : true //or false
"push_token_exist": true //or false
}
}
Example
{
"request": {
"application": "XXXXX-XXXXX", // Pushwoosh application code
"hwid": "hardware-device-id"
}
}

post
/setBadge

https://cp.pushwoosh.com/json/1.3/setBadge
Sends current badge value for a device to Pushwoosh. Called internally from the SDK.
Request
Response
Body Parameters
application
required
string
Pushwoosh application code.
hwid
required
string
Hardware device ID used in /registerDevice request.
badge
required
integer
Current badge on the application.
200: OK
{
"status_code":200,
"status_message":"OK"
}
Example
{
"request":{
"application" : "XXXXX-XXXXX", // Pushwoosh application code
"hwid": "8f65b16df378e7a6bece9614e1530fb2", // hardware device ID used in /registerDevice function call
"badge": 4 // current badge on the application
}
}

Called from the SDK internally. Sends current badge value for a device to Pushwoosh. This happens internally when app changes badge value on iOS device. Allows auto-incrementing badges to work properly.

This method IS NOT used to update the badge value on the device. Instead please use /createMessage request with the "ios_badges" parameter.

PHP
<?php
//see http://gomoob.github.io/php-pushwoosh/set-badge.html
use Gomoob\Pushwoosh\Model\Request\SetBadgeRequest;
// Creates the request instance
$request = RegisterDeviceRequest::create()
->setBadge(5)
->setHwid('HWID');
// Call the '/setBadge' Web Service
$response = $pushwoosh->setBadge($request);
if($response->isOk()) {
print 'Ok, operation successful.';
} else {
print 'Oups, the operation failed :-(';
print 'Status code : ' . $response->getStatusCode();
print 'Status message : ' . $response->getStatusMessage();
}

post
/applicationOpen

https://cp.pushwoosh.com/json/1.3/applicationOpen
Registers an app open event. Called internally from the SDK.
Request
Response
Body Parameters
application
required
string
Pushwoosh application code.
hwid
required
string
Hardware device ID used in /registerDevice request.
200: OK
{
"status_code":200,
"status_message":"OK"
}
Example
{
"request":{
"application" : "XXXXX-XXXXX", // Pushwoosh application code
"hwid": "8f65b16df378e7a6bece9614e1530fb2" // hardware device ID used in /registerDevice function call
}
}

post
/pushStat

https://cp.pushwoosh.com/json/1.3/pushStat
Registers a push open event. Called internally from the SDK.
Request
Response
Body Parameters
application
required
string
Pushwoosh application code.
hwid
required
string
Hardware device ID used in /registerDevice request.
userId
optional
string
The user ID to associate with the push open event.
hash
optional
string
Hash tag received in push notification ("p" parameter of the push payload).
200: OK
{
"status_code": 200,
"status_message": "OK",
"response": null
}
Example
{
"request":{
"application" : "XXXXX-XXXXX", // Pushwoosh application code
"hwid": "8f65b16df378e7a6bece9614e1530fb2", // hardware device ID used in /registerDevice function call
"userId": "USER012345", // the user id to associate with the push open event
"hash": "HASH_TAG" // hash tag received in push notification (“p” parameter in the push payload)
}
}
PHP
<?php
//see http://gomoob.github.io/php-pushwoosh/push-stat.html
use Gomoob\Pushwoosh\Model\Request\PushStatRequest;
// Creates the request instance
$request = PushStatRequest::create()
->setHash('hash')
->setHwid('HWID');
// Call the '/pushStat' Web Service
$response = $pushwoosh->pushStat($request);
if($response->isOk()) {
print 'Ok, operation successful.';
} else {
print 'Oups, the operation failed :-(';
print 'Status code : ' . $response->getStatusCode();
print 'Status message : ' . $response->getStatusMessage();
}

post
/messageDeliveryEvent

https://cp.pushwoosh.com/json/1.3/messageDeliveryEvent
Registers push delivery event for the device. Called internally from the SDK.
Request
Response
Body Parameters
application
required
string
Pushwoosh application code.
hwid
required
string
Hardware device ID used in /registerDevice request.
hash
optional
string
Hash tag received in push notification ("p" parameter of the push payload).
200: OK
{
"status_code": 200,
"status_message": "OK",
"response": null
}
Example
{
"request":{
"application" : "XXXXX-XXXXX", // Pushwoosh application code
"hwid": "8f65b16df378e7a6bece9614e1530fb2", // hardware device ID used in /registerDevice function call
"hash": "HASH_TAG" // hash tag received in push notification (“p” parameter in the push payload)
}
}

post
/setPurchase

https://cp.pushwoosh.com/json/1.3/setPurchase
Called internally from the SDK. Records a purchase event, populates "In-App Product" default tag, and increments value of "In-App Purchase" default tag.
Request
Response
Body Parameters
application
required
string
Pushwoosh application code.
transactionDate
required
string
Date of the transaction.
hwid
required
string
Hardware device ID used in /registerDevice request.
quantity
required
integer
Items quantity.
currency
required
string
Transaction currency.
productIdentifier
required
string
Product SKU.
price
required
number
Item price.
200: OK
{
"status_code":200,
"status_message":"OK",
"response": null
}
Example
{
"request":{
"transactionDate": "2014-10-30T10:55:14Z", // date of the transaction
"application": "XXXXX-XXXXX", // Pushwoosh application code
"hwid": "F6BA94A2-6BB2-XXXX-XXXX-E945C686240D", // hardware device ID used in /registerDevice function call
"quantity": 1, // items quantity
"currency": "USD", // transaction currency
"productIdentifier": "com.pushon.purchase.1", // product SKU
"price": 0.99 // item price
}
}

post
/deleteDevice

https://cp.pushwoosh.com/json/1.3/deleteDevice
Completely removes device from all applications on account.
Request
Response
Body Parameters
application
required
string
Pushwoosh app code.
hwid
required
string
Hardware device ID.
200: OK
{
"status_code": "200",
"status_message": "OK",
"response": null
}
Example
{
"request": {
"application":"XXXXX-XXXXX", // Pushwoosh app code
"hwid": "hardware-device-id"
}
}

post
/getNearestZone

https://cp.pushwoosh.com/json/1.3/getNearestZone
Called internally from the SDK. Gets the parameters of the nearest geozone and a distance to it. Also records the device location for geo push notifications.
Request
Response
Body Parameters
application
required
string
Pushwoosh application code.
hwid
required
string
Hardware device id used in /registerDevice request.
lat
required
string
Latitude of the device.
lng
required
string
Longitude of the device.
200: OK
{
"status_code":200,
"status_message":"OK",
"response": { // returns zone which is the closest to the position provided in the request
"name":"zone name",
"lat":42,
"lng":42,
"range":1234, // range in meters
"distance":4715784 // distance in meters
}
}
Example
{
"request": {
"application": "APPLICATION_CODE", // Pushwoosh application code
"hwid": "HWID", // hardware device ID used in /registerDevice function call
"lat": 10.12345, // latitude of the device
"lng": 28.12345 // longitude of the device
}
}
<?php
//see http://gomoob.github.io/php-pushwoosh/get-nearest-zone.html
use Gomoob\Pushwoosh\Model\Request\GetNearestZoneRequest;
// Creates the request instance
$request = GetNearestZoneRequest::create()
->setHwid('HWID')
->setLat(10.12345)
->setLng(28.12345);
// Call the '/getNearestZone' Web Service
$response = $pushwoosh->getNearestZone($request);
if($response->isOk()) {
print 'Zone name : ' . $response->getResponse()->getName();
print 'Latitude : ' . $response->getResponse()->getLat();
print 'Longitude : ' . $response->getResponse()->getLng();
print 'Range : ' . $response->getResponse()->getRange();
print 'Distance : ' . $response->getResponse()->getDistance();
} else {
print 'Oups, the operation failed :-(';
print 'Status code : ' . $response->getStatusCode();
print 'Status message : ' . $response->getStatusMessage();
}

post
/getTags

https://cp.pushwoosh.com/json/1.3/getTags
Retrieves a list of tags with corresponding values for the specific device.
Request
Response
Body Parameters
application
required
string
Pushwoosh application code.
userId
optional
string
User identifier to be used instead of "hwid". If used together with a "hwid", the "hwid" prevails.
hwid
optional
string
Hardware device ID used in /registerDevice request.
200: OK
{
"status_code": 200,
"status_message": "OK",
"response": {
"result": {
"Language": "fr"
}
}
}
Example
{
"request":{
"application": "XXXXX-XXXXX", // Pushwoosh application code
"hwid": "HWID", // optional, hardware device ID used in /registerDevice function call
"userId": "The ID of a specific user" // optional, can be used instead of "hwid" to retrieve tags for a specific user
}
}

post
/setTags

https://cp.pushwoosh.com/json/1.3/setTags
Sets tag values for the device. Called from the SDK.
Request
Response
Body Parameters
application
required
string
Pushwoosh application code.
hwid
required
string
Hardware device ID used in /registerDevice request.
tags
required
object
JSON object of tags to set, send 'null' to remove the value.
200: OK
{
"status_code":200,
"status_message":"OK",
"response": null
}

The method is called from SDK. It is possible to call it remotely from your backend, however you need to maintain an up-to-date database of hwid’s on the backend side.

Please avoid setting more that 50 tag values in a single /setTags request.

Example
{
"request":{
"application": "XXXXX-XXXXX", // Pushwoosh application code
"hwid": "8f65b16df378e7a6bece9614e1530fb2", // hardware device ID used in /registerDevice function call
"tags": {
"StringTag": "string value",
"IntegerTag": 42,
"ListTag": ["string1","string2"], // sets the list of values for Tags of List type
"DateTag": "2015-10-02 22:11", // note the time is in UTC
"BooleanTag": true, // valid values are - true, 1, false, 0, null
}
}
}

To extend the List Tag with new values, use the operation parameter with the "append" value as follows:

Example
{
"request": {
"hwid": "3d124a793575f189a5ca7dfd96e8aafd", // hardware device ID used in /registerDevice function call
"application": "61A79-C09B3", // Pushwoosh application code
"tags": {
"ListTag": {
"operation": "append", // appends following values to the Tag's list of values
"value": [ // values to append
"tag2",
"tag3"
]
}
}
}
}

For emails call /setEmailTags.

Status codes:

HTTP Status code

status_code

Description

200

200

Tags have been successfully set

200

210

Argument error. See status_message for more info.

400

N/A

Malformed request string

500

500

Internal error

PHP
<?php
//see http://gomoob.github.io/php-pushwoosh/set-tags.html
use Gomoob\Pushwoosh\Model\Request\SetTagsRequest;
// Creates the request instance
$request = SetTagsRequest::create()
->setTags(
array(
'StringTag' => 'string value',
'IntegerTag' => 'integer value',
'ListTag' => ['string1', 'string2']
)
)
->setHwid('HWID');
// Call the '/setTags' Web Service
$response = $pushwoosh->setTags($request);
if($response->isOk()) {
print 'Ok, operation successful.';
} else {
print 'Oups, the operation failed :-(';
print 'Status code : ' . $response->getStatusCode();
print 'Status message : ' . $response->getStatusMessage();
}