Request a demoPricingBlogRelease notesSupport

Device API

List of methods for working with devices

registerDevice

/registerDevice

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

Called internally from the SDK. Registers device for the application.

Request Body

NameTypeDescription

application*

string

Pushwoosh application code.

push_token

string

Push token for the device.

language

string

Language locale of the device. Must be a lowercase two-letter code according to ISO-639-1 standard.

hwid*

string

Unique string to identify the device (IDFV on iOS, randomly generated value on Android).

timezone

integer

Timezone offset in seconds for the device.

device_type*

integer

Device type. See possible values below.

email

string

Email address to register (use for email users instead of HWID and push token).

tags

object

Tag values to assign to the device registered.

{
   "status_code":200,
   "status_message":"OK",
   "response": null
}
Example
{
   "request":{
      "application": "XXXXX-XXXXX", // required, Pushwoosh application code
      "push_token": "dec301908b9ba8df85e57a58e40f96f523f4c2068674f5fe2ba25cdc250a2a41", // optional
      "hwid": "1CA68A12-8DAC-4BB7-BEE5-B756288B6D3C", // required, hardware device ID
      "idfa" : "AEBE52E7-03EE-455A-B3C4-E57283966239", // optional
      "timezone": 3600, // optional, offset in seconds
      "device_type": 1, // required, see the possible values below. For emails, use the "emails" params as described below. 
      "email": "email_address@domain.com", // use instead of "hwid" and "push_token" to register the email address for your email project
      "language": "en", // optional, ISO 639-1|639-2 language code
      "userId": "Alex", // optional
      "tags": { // optional, tag values to set for the device registered 
           "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 should be in UTC
           "BooleanTag": true  // valid values are: true, 1, false, 0, null
           },
  
      // system tags, optionals
      "app_version": "1.2.3", 
      "device_model": "Samsung SM-G355H",
      "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

  • 3 – Android

  • 7 – OS X

  • 8 – Windows 8

  • 9 – Amazon

  • 10 – Safari

  • 11 – Chrome

  • 12 – Firefox

To register a email subscriber for your app, send the "email": "email_address@domain.com" param in your /registerDevice or /registerEmail request as follows:

Email registration request
{
   "request":{
      "application": "XXXXX-XXXXX", // required, Pushwoosh application code
      "email": "email_address@domain.com", // required, email address to register for your email project
      "language": "en", // optional, ISO 639-1|639-2 language code
      "userId": "Alex", // optional
      "tags": { // optional, tag values to set for the device registered 
           "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 should be in UTC
           "BooleanTag": true  // valid values are: true, 1, false, 0, null
           }
   }
}

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();
}

unregisterDevice

/unregisterDevice

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

Removes the device's push token. The unregistered device is still counted in Total Devices and can be reached with In-Apps. Called internally from the SDK.

Request Body

NameTypeDescription

application*

string

Pushwoosh application code.

hwid*

string

Hardware device ID used in /registerDevice request.

{
    "status_code": 200,
    "status_message": "OK",
    "response": null
}
Example
   {
       "request":{
          "application": "XXXXX-XXXXX", // required, Pushwoosh application code
          "hwid": "8f65b16df378e7a6bece9614e1530fb2" // required, 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();
}

setTags

/setTags

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

Sets tags values for the device. Called from the SDK.

Request Body

NameTypeDescription

application*

string

Pushwoosh application code.

hwid*

string

Hardware device ID used in /registerDevice request.

tags*

object

JSON object of tags to set, send "null" to remove the value.

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

The method is called from the 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.

Example
{
   "request":{
      "application": "XXXXX-XXXXX", // required, Pushwoosh application code
      "hwid": "8f65b16df378e7a6bece9614e1530fb2", // required, hardware device ID used in /registerDevice function call
      "tags": { // required
           "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
      }  
   }
}

Increment Integer tag values

To increment a value of the Integer Tag, use the operation parameter with the "increment" value as follows: 

{
   "request":{
      "application": "12345-67890", // required, Pushwoosh application code
      "hwid": "21AB7628-F83F-4R9N-CCC0-PO287CS24CA4", // required, hardware device ID used in /registerDevice function call
      "tags": { // required
           "Level": { // Tag name
               "operation": "increment", // overwrites the integer tag in increments of the following value 
               "value": 1 // increment for the tag value
           }  
      }  
   }
}

Decrement Integer tag values

To decrement, use the negative numbers as the value for the "increment" operation (-1, -2, -3,-n): 

{
   "request":{
      "application": "12345-67890", // required, Pushwoosh application code
      "hwid": "21AB7628-F83F-4R9N-CCC0-PO287CS24CA4", // required, hardware device ID used in /registerDevice function call
      "tags": { // required
           "Level": { // Tag name
               "operation": "increment", // overwrites the integer tag in decrement of the following value 
               "value": -1 // decrement for the tag value
           }  
      }  
   }
}

Append List tag values

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

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

Remove List tag values

To remove some values from the List Tag, use the "remove" operation as follows: 

{
   "request":{
      "application": "12345-67890", // required, Pushwoosh application code
      "hwid": "21AB7628-F83F-4R9N-CCC0-PO287CS24CA4", // required, hardware device ID used in /registerDevice function call
      "tags": { // required
           "In-App Product": { // Tag name
               "operation": "remove", // removes the following values from the list tag
               "value": "outwear_02" // value or values to remove
           }
      }  
   }
}

Set tags by UserID

To set tags for all devices associated to a particular User ID, use the "userId" parameter instead of "hwid".

Make sure the tag you're setting values for is user-specific.

Example
{
   "request":{
      "application": "AAAAA-BBBBB", // Pushwoosh app code
      "userId": "some_user", // user ID you'd like to set tags for 
      "tags": { // tags and values to set
           "Language": "es"

      }  
   }
}

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();
}

setBadge

/setBadge

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

Sends current badge value for a device to Pushwoosh. Called internally from the SDK.

Request Body

NameTypeDescription

application*

string

Pushwoosh application code.

hwid*

string

Hardware device ID used in /registerDevice request.

badge*

integer

Current badge on the application.

{
   "status_code":200,
   "status_message":"OK"
}
Example
  {
       "request":{
          "application" : "XXXXX-XXXXX", // required, Pushwoosh application code
          "hwid": "8f65b16df378e7a6bece9614e1530fb2", // required, hardware device ID used in /registerDevice function call  
          "badge": 4 // required, 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();
}

applicationOpen

/applicationOpen

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

Registers an app open event. Called internally from the SDK.

Request Body

NameTypeDescription

application*

string

Pushwoosh application code.

hwid*

string

Hardware device ID used in /registerDevice request.

{
   "status_code":200,
   "status_message":"OK"
}
Example
  {
       "request":{
          "application" : "XXXXX-XXXXX", // required, Pushwoosh application code
          "hwid": "8f65b16df378e7a6bece9614e1530fb2" // required, hardware device ID used in /registerDevice function call    
       }
    }

pushStat

/pushStat

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

Registers a push open event. Called internally from the SDK.

Request Body

NameTypeDescription

application*

string

Pushwoosh application code.

hwid*

string

Hardware device ID used in /registerDevice request.

userId

string

The user ID to associate with the push open event.

hash

string

Hash tag received in push notification ("p" parameter of the push payload).

{
    "status_code": 200,
    "status_message": "OK",
    "response": null
}
Example
    {
       "request":{
          "application" : "XXXXX-XXXXX", // required, Pushwoosh application code
          "hwid": "8f65b16df378e7a6bece9614e1530fb2", // required, hardware device ID used in /registerDevice function call 
          "userId": "USER012345", // optional, the user id to associate with the push open event 
          "hash": "HASH_TAG" // optional, 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();
}

messageDeliveryEvent

/messageDeliveryEvent

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

Registers push delivery event for the device. Called internally from the SDK.

Request Body

NameTypeDescription

application*

string

Pushwoosh application code.

hwid*

string

Hardware device ID used in /registerDevice request.

hash

string

Hash tag received in push notification ("p" parameter of the push payload).

{
    "status_code": 200,
    "status_message": "OK",
    "response": null
}
Example
 {
       "request":{
          "application" : "XXXXX-XXXXX", // required, Pushwoosh application code
          "hwid": "8f65b16df378e7a6bece9614e1530fb2", // required, hardware device ID used in /registerDevice function call  
          "hash": "HASH_TAG" // optional, hash tag received in push notification (“p” parameter in the push payload) 
       }
 }
PreviousPreset properties mapNextTags API

Last updated

#1600: moved in-app statistics to in-apps, added a link to statistics

Change request updated