Contact devices

Creating new devices

To create a new device you can use the /contacts/{:cid}/devices endpoint. The method is POST.

The following fields are required:

  • deviceName
  • appId
  • platform
  • deviceOS
  • appVersion
  • deviceModel
  • pushToken

High-level request elements

deviceName

String

Specifies the name of the device for visual reference in the UI.

appId

String

Specifies the ID of the app installed on the device. This ID refers to the apps endpoint > App ID.

appVersion

String

The version of your app installed on the contact’s device. This is purely meta information that helps to understand the push success/failure based on the app version, if any.

platform

String

Specifies the app’s platform. The value can be one of:

  • APNS: For Production APNS apps.
  • APNS_SANDBOX: For Sandbox APNS apps.
  • GCM: For FCM/GCM apps.

deviceOS

String

Specifies the device OS. The value can be either:

  • iOS
  • Android

deviceModel

String

Specifies the model of the contact’s device.

status

String

Specifies the status of the device. Push notifications will be only sent to the active devices under a given contact. It can be one of:

  • ACTIVE (A)
  • DISABLED (D)
  • DELETED (E)

Note: The default value is ‘Active’.

pushToken

String

Specifies the pushToken (also known as the deviceToken) given to your app by APNS/GCM to receive the push notification.


Notes:

  • Ensure that the deviceName is unique for each device.
  • Ensure that the values for deviceOS and deviceModel are properly set. Don’t leave them blank or give invalid/erroneous data. These values are the ones that are shown on the UI and in the reports. So proper values gives you an easier way to identify the devices under a given contact.
  • Ensure that before the device is created, you have the appID and the push token values available.
  • A contact can have as many devices as needed, but the number is limited to the value set in the deviceLimit in APP creation on the /apps endpoint. You can set it to a maximum of 10 per contact.
  • JSON
  • XML

Creating new devices

New devices can only be created under a given contact easily by following the request structure:

{{codeStart}}

POST https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices?apikey=[your_api_key]

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Content-Type: application/vnd.whispir.contactdevice-v1+json

{

"deviceName": "BCDF6B61-CA55-F287FF272101-4496-9DA9",

"appId": "B1A24A8BF2DBB10E",

"platform": "APNS",

"deviceOS": "IOS 9",

"deviceModel": "Iphone X",

"status": "active",

"pushToken": "15a01046 16f6f4f9 2f2055b5 f12d2c93 a70de908 487762f9 7b6c7115 e30083b1"

}

{{codeEnd}}

 

The successful response will be a 201 response with the details of the device created and its associated unique deviceID.

{{codeStart}}

{

"id": "1B0C3FC62D59BF90",

"deviceName": "BCDF6B61-CA55-F287FF272101-4496-9DA9",

"appId": "B1A24A8BF2DBB10E",

"registrationDate":"2019-11-17",

"lastModifiedDate":"2019-11-17",

"platform": "APNS",

"deviceOS": "IOS 9",

"deviceModel": "Iphone X",

"status": "active",

"pushToken": "15a01046 16f6f4f9 2f2055b5 f12d2c93 a70de908 487762f9 7b6c7115 e30083b1",

"link": [

{

"uri": "https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices/1B0C3FC62D59BF90?apikey=[your api key]",

"rel": "self",

"method": "GET"

},

{

"uri": "https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices/1B0C3FC62D59BF90?apikey=[your api key]",

"rel": "updateDevice",

"method": "PUT",

"type": "application/vnd.whispir.contactdevice-v1+json,application/vnd.whispir.contactdevice-v1+xml"

},

{

"uri": "https://api.<region>.whispir.com/workspaces/{:wid}/contacts/{:cid}/devices/1B0C3FC62D59BF90?apikey=[your api key]",

"rel": "deleteDevice",

"method": "DELETE"

}

]

}

{{codeEnd}}