Device API
registerDevice
POST
https://api.pushwoosh.com/json/1.3/registerDevice
Called internally from the SDK. Registers device for the application.
Request Body
Name | Type | Description |
---|---|---|
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. |
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}
{ "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "push_token": "dec301908b9ba8XXXXX57a58e40f96f5XXXXX2068674f5XXXXa25cdc250a2a41", // optional. "hwid": "1CA6XXXXX-8DAC-XXXXX-XXXXX-B756288B6D3C", // required. Hardware device ID "idfa": "AEBE52E7-0XXXXX-455A-XXXXX-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": "2024-10-02 22:11", // note the time should be in UTC "BooleanTag": true // valid values are: true, false },
// 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/HBXXXXX/orcXXXXX/scS5CFP6XXXXXHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=", "auth_token": "RlRmCXXXXX/s7XXXXXjKFzoQ==",
// optional FCM keys for Chrome (for XMPP) "fcm_token": "BNmDO4BTKEMJXXXXXprTf7t/XXXXXBQ/orXXXXXc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=", "fcm_push_set": "RlXXXXXGM/s7XXXXXjKFzoQ==" }}
Possible device types:
- 1 – iOS
- 3 – Android
- 7 – Mac OS X
- 8 – Windows
- 9 – Amazon
- 10 – Safari
- 11 – Chrome
- 12 – Firefox
- 17 – Huawei
- 18 – SMS
- 21 – WhatsApp
Registering email devices
To register a email subscriber for your app, send the "email": "email_address@domain.com"
param in your /registerDevice
or /registerEmail
request as follows:
Request example
{ "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": "2024-10-02 22:11", // note the time should be in UTC "BooleanTag": true // valid values are: true, false } }}
Registering WhatsApp devices
To register a WhatsApp device for your app, follow these guidelines:
-
hwid: Ensure this field includes the whatsapp: prefix followed by the phone number in E.164 format (e.g., whatsapp:+0000000000). The phone number must be valid, which Pushwoosh will verify.
-
Push token: A push token is not required, as hwid will automatically function as the push token.
-
device_type: Set this field to 21 to specify WhatsApp as the platform.
Request example
{ "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "whatsapp:+0000000000", // required. WhatsApp prefix and valid phone number "timezone": 3600, // optional. Time offset in seconds "device_type": 21, // required. WhatsApp device type is 21 "language": "en", // optional. ISO 639-1|639-2 language code "userId": "Alex", // optional. User identifier "tags": { // optional. Tag values for custom segmentation "StringTag": "string value", "IntegerTag": 42, "ListTag": ["string1", "string2"], "DateTag": "2024-10-02 22:11", // UTC format "BooleanTag": true }, "app_version": "1.2.3", // optional. Application version "device_model": "Samsung SM-G355H", // optional. Device model "os_version": "2.3" // optional. Operating system version }}
Registering SMS devices
To register an SMS device for your app, follow these guidelines:
-
hwid: Ensure this field includes the phone number in E.164 format (e.g., +0000000000). The phone number must be valid, which Pushwoosh will verify.
-
Push token: A push token is not required, as hwid will automatically function as the push token.
-
device_type: Set this required field to 18 to designate SMS as the platform.
Request example
{ "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "+0000000000", // required. Valid phone number in E.164 format "timezone": 3600, // optional. Time offset in seconds "device_type": 18, // required. SMS device type is 18 "language": "en", // optional. ISO 639-1|639-2 language code "userId": "Alex", // optional. User identifier "tags": { // optional. Tag values for custom segmentation "StringTag": "string value", "IntegerTag": 42, "ListTag": ["string1", "string2"], "DateTag": "2024-10-02 22:11", // UTC format "BooleanTag": true }, "app_version": "1.2.3", // optional. Application version "device_model": "Samsung SM-G355H", // optional. Device model "os_version": "2.3" // optional. Operating system version }}
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 |
bulkRegisterDevice
Registers multiple devices in Pushwoosh in a single request. It also allows specifying various tags for each device.
POST
https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
application | string | Yes | The application code for your Pushwoosh account. |
auth | string | Yes | The API authentication token. |
devices | array | Yes | An array of device objects. Each object represents a device and its associated data. See details in the Device object parameters table below. |
Device object parameters
Parameter | Type | Required | Description |
---|---|---|---|
hwid | string | Yes | The hardware ID or unique identifier for the device. |
push_token | string | Yes | Push token for the device. |
platform | integer | Yes | The platform identifier. Learn more |
list_operator | string | No | Determines the action for list-type tags: - “append”: Add the specified value to the tag list. - “remove”: Remove the specified value from the tag list. Note: If the list_operator parameter is not specified, all existing values in the tag list will be replaced with the provided values. |
tags | object | No | Custom tags assigned to the device. Tags are key-value pairs used for segmentation. |
Request example
{ "application": "application code", // required. Pushwoosh app code "auth": "Pushwoosh auth token", // required. API access token from Pushwoosh Control Panel "devices": [{ // required. Array of devices "hwid": "device hwid", // required. Unique identifier for the device (can be an email). "push_token": "device push token", // required. Push notification token for the device. "platform": 14, // required. Device platform (e.g., 14 for email). "list_operator": "append", // optional. For list tags. Adds or removes the specified value(s) from the tag of list type. "tags": { // optional. Values to set for the specified tags. "language": "en", // use correct value type. "CSV_Import": "summer_camp" } }, { "hwid": "device hwid 2", // required. Unique identifier for the second device. "push_token": "device push token 2", // required. Push notification token for the device. "platform": 14, // required. Device platform. "list_operator": "remove", // optional. Adds or removes values from tags of the list type. "tags": { // optional. Values to remove from the specified tags. "language": "en", "CSV_Import": "summer_camp2" } }, { "hwid": "device hwid 3", // required. Unique identifier for the third device. "push_token": "device push token 3", // required. Push notification token for the device. "platform": 14, // required. Device platform. "tags": { // optional. Values to set for the specified tags. "language": "en", "CSV_Import": "summer_camp3" } }]}
Response
The method responds with an operation ID, which can be used to track the status and results of the bulk registration process.
{ "request_id": "request_id to use in GET method to obtain job status", "status": "Pending"}
Checking bulkRegisterDevice status
You can check the status of a bulk registration process by making the following GET request:
GET
https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice/{request_id}?detailed=true
Parameter | Type | Required | Description |
---|---|---|---|
request_id | string | Yes | The request ID returned by the POST request. |
detailed | boolean | No | If set to true , the response includes detailed results for each registered device. |
Example response
{ "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782", "status": "Completed", "progress": 100, "devices_success": 4, "devices": [ { "hwid": "user1@example.com", "status": "done" }, { "hwid": "user2@example.com", "status": "done" }, { "hwid": "user3@example.com", "status": "done" }, { "hwid": "invalid_email@example.com", "status": "failed" } ]}
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
Name | Type | Description |
---|---|---|
application* | string | Pushwoosh application code. |
hwid* | string | Hardware device ID used in /registerDevice request. |
{ "status_code": 200, "status_message": "OK", "response": null}
{ "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16XXXXXe7a6beceXXXXX530fb2" // required. Hardware device ID used in /registerDevice API }}
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 |
setTags
POST
https://go.pushwoosh.com/json/1.3/setTags
Sets tags values for the device. Called from the SDK.
Request Body
Name | Type | Description |
---|---|---|
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}
{ "request":{ "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16XXXXXe7a6becXXXXXe1530fb2", // required. Hardware device ID used in /registerDevice API "tags": { // required. "StringTag": "string value", "IntegerTag": 42, "ListTag": ["string1", "string2"], // sets the list of values for Tags of List type "DateTag": "2024-10-02 22:11", // note the time is in UTC "BooleanTag": true // valid values are - true, false } }}
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-XXXX-XXXX-CCC0-PO287CS24CA4", // required. hardware device ID used in /registerDevice API "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-XXXX-XXXX-CCC0-PO287CS24CA4", // required. Hardware device ID used in /registerDevice API "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:
{ "request": { "hwid": "3d124a79XXXXf189XXXX7dfd9XXXXafd", // required. Hardware device ID used in /registerDevice API "application": "6XXXX-XXXX3", // 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-XXXX-XXXX-CCC0-PO287CS24CA4", // required. Hardware device ID used in /registerDevice API "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”.
{ "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" } }}
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 |
getTags
POST
https://go.pushwoosh.com/json/1.3/getTags
Retrieves a list of tags with corresponding values for the specific device.
Request Body
Name | Type | Description |
---|---|---|
application* | string | Pushwoosh application code. |
userId | string | User identifier to be used instead of “hwid”. If used together with a “hwid”, the “hwid” prevails. |
hwid | string | Hardware device ID used in /registerDevice request. |
{ "status_code": 200, "status_message": "OK", "response": { "result": { "Language": "fr" } }}
{ "request":{ "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "HWID", // optional. Hardware device ID used in /registerDevice API "userId": "USER_ID" // optional. Can be used instead of "hwid" to retrieve tags for a specific user }}
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
Name | Type | Description |
---|---|---|
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"}
{ "request":{ "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16dXXXXe7a6XXXX9614XXXX0fb2", // required. Hardware device ID used in /registerDevice API "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.
applicationOpen
POST
https://api.pushwoosh.com/json/1.3/applicationOpen
Registers an app open event. Called internally from the SDK.
Request Body
Name | Type | Description |
---|---|---|
application* | string | Pushwoosh application code. |
hwid* | string | Hardware device ID used in /registerDevice request. |
{ "status_code": 200, "status_message": "OK"}
{ "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16dXXXXe7a6XXXX9614eXXXXfb2" // required. Hardware device ID used in /registerDevice API }}
pushStat
POST
https://api.pushwoosh.com/json/1.3/pushStat
Registers a push open event. Called internally from the SDK.
Request Body
Name | Type | Description |
---|---|---|
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}
{ "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16dfXXXX7a6beXXXX14e1530fb2", // required. Hardware device ID used in /registerDevice API "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) }}
messageDeliveryEvent
POST
https://api.pushwoosh.com/json/1.3/messageDeliveryEvent
Registers push delivery event for the device. Called internally from the SDK.
Request Body
Name | Type | Description |
---|---|---|
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}
{ "request": { "application": "XXXXX-XXXXX", // required. Pushwoosh application code "hwid": "8f65b16dfXXXX7a6bece9XXXX1530fb2", // required. Hardware device ID used in /registerDevice API "hash": "HASH_TAG" // optional. Hash tag received in push notification // ("p" parameter in the push payload) }}