This document contains all of the relevant information required for send a push though the Xtify Push API v2.0.

1.1 Sending an Instant Simple or Rich Notification via API

Overview

The Xtify Push API allows you to immediately send a message to a set of users that you can select by XID, positive or negative tags, or a "send to all" flag. By exposing our push interface via API, you can generate timely one-off notifications and event-based messages from within your own service either by hand or automatically. 

URL

http://api.xtify.com/2.0/push

Http Method

POST

Request Content

Note that only one user selector can be specified to avoid conflicts in prioritization. Selectors are listed below (only the "hasTags" and "notTags" fields can be used in conjunction.)

Content Sub-Document

Action Sub-Document

Providing a primary action for your push will let you refine your users' experience upon receiving an alert. Most devices support each action type with a few exceptions.

Simple Action Types:

• URL: Forward your users to the HTTP address specified in the "data" field. Enabled in all devices.
• RICH: Open the rich inbox and the rich notification that was provided in the "rich" field. Available in GCM and iOS.
• CUSTOM: This is specific to each device, and enabled in all devices except for BlackBerry.
  • iOS: Serialized (string-ified) JSON key value pairs to be passed in the APNS message. e.g. "{ "acme1" : "bar", "acme2" : 42 }"
  • GCM and Android: Provide a custom intent in the "data" field to be run upon the user selecting this action. e.g. "com.xtify.custom.intent"
• PHONE: Opens the dialer. Only available if specified as the rich action type on iOS
• DEFAULT: Default device behavior. This will be supplied implicitly if no action is provided.
• NONE: All visual and audible alerts will be suppressed. Use this feature to send data to an application without disrupting the user.

Rich Action Types:

• WEB: Forward your users to the HTTP address specified in the "data" field. Enabled in all devices.
• CST: Any custom format you'd like and will handle in your app.
• PHN: Opens the dialer. Only available if specified as the rich action type on iOS
• DEFAULT: Default device behavior. This will be supplied implicitly if no action is provided.
• NONE: No action will be presented in the rich message presentation.

Request Format

This following document is for formatting purpose only and won't be used in a production application. For example, you wouldn't have sendAll with Tags and XIDs in a push payload. For working examples, check our out github repo.

Response Content

Error Codes

Errors will conform to HTTP standard responses. Additional information may be provided in the reason phrase if available.

iOS Examples

Simple push with customized key value pairs:
{
          "apiKey":"12345678-7d94-415a-9eed-00987654321",
          "appKey":"12345678-4ab7-4633-8a7c-00987654321",
           "xids": ["517eb971534c5cddc6cbcfff",
                      "517eb971534c5cddc6cbcccc"],
           "content": {
                      "message": "Arma virumque cano, troique primus ab oris",
                      "sound": "ding.caf",
                      "badge": "+1",
                      "action": {
                      "type": "RICH",
                      "label":"Open"
           },
           "rich": {
                      "subject": "Arma virumque cano",
                      "message": "<h2>Arma virumque cano, troique primus ab oris Italiam fato profugus Laviniaque venit litora, multum ille et terris iactatus et alto vi superum, saevae memorem Iunonis ob iram, multa quoque et bello passus, dum conderet urbem inferretque deos Latio; genus unde latinum Albanique patres atque altae moenia Romae.</h2>"
                      }
           }
}

Simple push with customized key value pairs:
{

    "apiKey":"12345678-7d94-415a-9eed-12345678",
    "appKey":"12345678-4ab7-4633-8a7c-12345678",
    "xids": ["517eb971534c5cddc6cbcccc",
                "517eb971534c5cddc6cbcfff"
              ],
    "content": {
           "message": "Arma virumque cano, troique primus ab oris",
          "sound": "default.caf",
          "badge": "+1",
          "action": {
                    "type": "CUSTOM",
                    "label":"Open",
                    "data": "{'action_id': 'ABC', inum: '123456'}"
          }
     }
}

Service Limits

• The default service limits you to 50 connections per IP address over 10 second period. Enterprise or Premium support customers can have this threshold increased.
• There is a 256 byte limit on the total package size for iOS notifications. After core JSON message overhead, you're left with 189 bytes for the remaining simple notification content (including uses JSON element names and data).
• GCM has a payload limit of 4096 bytes. 
• Xtify doesn't enforce a limit on the size of your XID array, your request is limited to the size of HTTP Post. If you plan on sending messages to a large quantity of individual XIDs, we suggest batching in groups of 1,000. Better yet, group your users first by Tag or use the sendAll option.