The EachScape push notification API allows you to interact with the push notification subsystem to send messages targeted to a particular device.

 

Accessing the API

In order to access the API you will need to POST to the URL https://push.eachscape.com/api/targeted.json and supply these parameters:

  • api_key A string we will supply that uniquely identifies your application. Each API key is restricted in what it can do and which app it can access. This field is 64 characters long.
  • device A string that identifies the device you want to send to. Under the covers this string tells us enough information to get to the device. It begins with the string "android" or "ios" and is divided into 3 parts with the pipe (|) character. The length of this field is dependent on values set by Apple, Google and device manufacturers; currently the longest values we have observed are 185 characters and we believe that it will never exceed 250 characters in length.
  • alert The text message you want to send to the device. The alert message is limited to 180 characters.

Example Request using curl:

Replace <api_key>, <device string> (see below) and <message> with the values appropriate to your app, the targeted device and the message you want to send.

curl -XPOST -d 'api_key=<api_key>&device=<device string>&alert=<message>' https://push.eachscape.com/api/targeted.json

When Everything Works

The server will return an HTTP status code value of 200. The message body will contain a JSON response that looks like this.

 

{"error_code":0, 
  "error_message":"No error",
  "id":143,
  "message_id":"API-123-T-1323993824.62776"}

What Can Go Wrong?

There are a few conditions that you might encounter in using the API. These are generally returned via HTTP status codes:

  • Forbidden (403) generally indicates you are not using SSL (https protocol scheme) to access the API.
  • Unauthorized (401) indicates that the API key is not valid.
  • Gone (410) indicates the specified device is unknown to the server.
  • Bad Request (400) indicates that the creation of the message failed. Generally this will occur if the alert message is longer than 180 characters.

Some of these errors may include elements in the body structure indicating the error status in more detail.

Getting The Device String

Inside an app, the Device String can be generated with this expression

 

[[sys:os]]|[[var:_deviceIdentifier]]|[[sys:pushNotificationDeviceToken]]