LATEST VERSION: 1.9 - CHANGELOG
Push Notification Services v1.8

Push

Push a message

POST /v1/push

Push a message out to a list of devices or devices targeted by platform.

Authentication: HTTP Basic application_uuid:api_key

Query Parameters: None

Request Body:

There are many possible options for the request body. All of the options are listed in the JSON text example below. Note that most of the individual JSON fields are optional. The options you need to use are described below. Several examples are illustrated below.

The messagebody field in the JSON request body is the default message that is supplied in notifications to remote devices. It will be overridden by any platform-specific custom message body data.

In particular, iOS devices will receive the messagebody field as their alert message unless the customiosalertbody field is populated. Android devices will receive the messagebody field in their payload message field unless the customandroidmessage field is populated.

Response Data, status: 200 (OK)

The fields returned by the /v1/push POST API depend on the type of push notification that was requested: scheduled or immediate.

If the push is given scheduleAt or scheduleIn fields then the push is scheduled to be delivered in the future. These pushes will return a schedule_id field in the response data. These schedule_id values can be used in the /v1/schedule APIs to update or cancel the scheduled push before it is delivered.

Otherwise the push will be queued to be sent immediately. In this case, the response will also contain a receipt_id field that can be used to follow the push notification delivery status in the audit logs.

Response Data

{
  "schedule_id": "",  # only returned if the push notification is a scheduled push
  "receipt_id": ""    # only returned if the push is being delivered immediately.
}

Scheduled pushes are described further below.

Targeting / Audience Selection

You can target your push notifications in many ways:

  • By platform(s). e.g.: “ios”, “android”.

  • By device UUID(s):

    • Devices UUIDs are determined by:
      • the device registration process in the PCF Push Client SDKs. See the documentation for the iOS or Android SDKs.
      • or by the /v1/registration POST/PUT APIs if you are registering your devices without using the Client SDKs.
  • By topic(s):

  • By Custom User ID:

    • Custom User IDs are created via the Register a device API /v1/registration POST APIs.
    • Sending a push to a Custom User ID:
      • the push will be sent simultaneously to all devices registered with this Custom User ID.
  • By Custom User ID and Topic(s):

    • Sending a push to a Custom User ID and Topic(s):
      • the push will be sent simultaneously to all devices registered with this Custom User ID and all devices registered with any of the provided Topic(s).
Key Description
devices A list of up to 4096 device UUIDs to target. These device UUIDs are the same ones that are returned by the PCF Push Client SDKs after registration or by the /v1/registration HTTP POST call if you are registering your devices without using the Client SDKs.
topics A list of up 1024 topics (formerly tags) to which devices may be subscribed. Only devices subscribed to one of more of the listed topics will be targeted. Devices select which topics to subscribe to by calling the appropriate subscribeToTopics methods in the client SDKs or by calling the /v1/registration HTTP POST or PUT.
platforms A list of platforms to be targeted. Available platforms are ‘ios’, 'android’, 'windows8’, 'windowsPhone’.
platform DEPRECATED. Possible values are 'all’, 'ios’, 'android’, 'windows8’, 'windowsPhone’. If 'platforms’ is also populated the platform(s) selected here will be added to list of platforms.
interactive-only If set to true then only those devices that can accept interactive pushes are targetted. At this time only iOS 8+ or Android 4.1+ devices are considered to support interactive pushes.
custom_user_ids A list of IDs for devices that is meaningful to your system, such as their login. The same Custom User ID can be used to refer to multiple devices.

LIMITS

Pushing to multiple targets is bounded by the following limits per request:

  • Devices: 4096
  • Custom User Ids: 4096
  • Topics: 1024

NOTES

  • At least one of devices, topics, platforms, or platform is required.

  • devices will override any other targeting type. Any topics, platforms, or platform targetting key will be ignored if there is a devices key.

  • topics and platforms can be used in a complementary way to push a message to just a subset of users (See example below).

  • Devices only need to be subscribed to at least one of the topics in the targetting data in order to receive the message (See example below). There is no way using the Push API to send a message to a device that is subscribed to all of the topics in a list.

Target Examples

  • Sending push messages to three specific devices (specified by their device UUIDs):
  {
    ...
      "target": {
        "devices": [ "device_uuid1", "device_uuid2", "device_uuid3" ]
      }
    ...
  }
  • Sending pushes to all devices (regardless of platform) subscribed to one of two specific topics (a device only needs to be subscribed to one of the topics in the list of topics in order to receive the message).
  {
    ...
    "target": {
      "topics": [ "exciting_topic", "pedantic_topic" ]
    }
    ...
  }
  • Sending pushes to all iOS devices:
  {
    ...
    "target": {
      "platforms": [ "ios" ]
    }
    ...
  }
  • Sending pushes to all “Android” devices subscribed to one specific topic:
  {
    ...
    "target": {
      "platforms": [ "android" ],
      "topics": [ "best_topic_ever" ]
    }
    ...
  }
  • Sending pushes to interactive only devices:
  {
    ...
    "target": {
      "platforms": [ "android", "ios" ],
      "interactive-only": true
    }
    ...
  }
  • Sending pushes to devices registered with a Custom User ID:
  {
    ...
    "target": {
      "custom_user_ids": [ "some_customer_user_id", "some_other_custom_user_id" ]
    }
    ...
  }
  • Sending pushes to devices registered with a Custom User ID and devices registered with Topic(s):
  {
    ...
    "target": {
      "custom_user_ids": [ "some_customer_user_id" ],
      "topics": [ "exciting_topic", "pedantic_topic" ]
    }
    ...
  }
  • Sending pushes to devices registered with Custom User IDs and devices registered with Topic(s):
  {
    ...
    "target": {
      "custom_user_ids": [ "some_customer_user_id1", "some_customer_user_id2" ],
      "topics": [ "exciting_topic", "pedantic_topic" ]
    }
    ...
  }

Setting Expiration Time on Pushes

The “expiryTime” field can be used to specify a time after which a push should not be displayed. It should be an Epoch timestamp integer in milliseconds (i.e.: the number of milliseconds since midnight January 1, 1970). If expiryTime is not set the behavior will be the platform default. For iOS and Android pushes will be queued for delivery if the target device is unreachable at the time of the push and delivered as soon as it is reachable. If expiryTime is set and the the device becomes reachable AFTER the expiry time, the push will not be delivered.

Windows 8 behavior is similar for tile and badge notifications but only one tile and one badge notification will be queued. See the Push notification service request and response headers documentation for more information.

IMPORTANT NOTE:

  • If omitted, the default expiry time used for Apple devices is Integer.MAX_VALUE seconds (i.e.: sometime in the year 2038).
  • If omitted, the default expiry time used on GCM is 4 weeks (2,419,200 seconds). The maximum time-to-live for messages delivered on GCM is also 4 weeks.
  • Windows 8 toast notifications are not queued and cannot have an expiry time. They will only be delivered at the time the push is sent if the target device is connected.
  • Windows Phone 7 has no expiry option. Instead pushes fall into one of three categories: immediate, up to 450 seconds, or up to 900 seconds. Depending on the time set in the “expiryTime” field, a push to Windows Phone 7 will be slotted into one of those categories. See the Sending push notifications for Windows Phone documentation.

Scheduled Pushes

Pushes can be scheduled to be sent at a later time. Use the scheduleAt field to specify the time when the push should be sent. As with expiryTime this should be an Epoch timestamp integer in milliseconds. Alternatively you can use the scheduleIn field to specify the scheduled time as the number of seconds from the time the server receives the push request. NOTE: You cannot set both the scheduleAt and scheduleIn fields at the same time as doing this would result in an error message from the server.

If the scheduled time is less than a preconfigured time in the future, the push will not be scheduled and will be sent immediately. By default this amount is 60 seconds.

Scheduled Pushes Examples

  • Scheduling a push message to be delivered for February 2, 2016 at 8 AM (UTC):
  {
    ...
    "scheduleAt": 1454313600000
    ...
  }
  • Scheduling a push message to be delivered two hours from now:
  {
    ...
    "scheduleIn": 7200000
    ...
  }

Custom Fields for Platform specific Pushes

Custom Fields for iOS Pushes

The fields available in the custom block for iOS are described here:

{
  "ios": {
    "alert": {
      "body": "iOS only message body",
      "action-loc-key": "actionKey",
      "loc-key": "localizedStringKey",
      "loc-args": [
        ""
      ],
      "title": "Title",
      "title-loc-key": "titleKey",
      "title-loc-args": [
        "arg1",
        "arg2"
      ],
      "launch-image": "Default.png"
    },
    "category": "SAMPLE_CATEGORY",
    "badge": 1,
    "sound": "default",
    "content-available": true,           # Note - the Push API expects this field to be a boolean. (see below)
    "extra": { "freeform custom data" : "freeform custom data", ... }
  }
}
  • extra
    type: dictionary or null
    This property can be used to pass free-form arbitrary payload data to the receiving iOS device. This data will be passed in the userInfo dictionary in the application:didReceiveRemoteNotification callback in the application’s app delegate class. It is up to the application to use this data as it needs.

  • alert
    type: string or dictionary
    If this property is included, the system displays a standard alert. You may specify a string as the value of alert or a dictionary as its value. If you specify a string, it becomes the message text of an alert with two buttons: Close and View. If the user taps View, the app is launched. Alternatively, you can specify a dictionary as the value of alert. See Table 3-2 at the Apple Documentation for descriptions of the keys of this dictionary.

  • badge
    type: number
    The number to display as the badge of the app icon. If this property is absent the badge is not changed. To remove the badge, set the value of this property to 0.

  • sound
    type: string
    The name of a sound file in the app bundle. The sound in this file is played as an alert. If the sound file doesn’t exist or default is specified as the value, the default alert sound is played. The audio must be in one of the audio data formats that are compatible with system sounds; see Preparing Custom Alert Sounds for details.

  • content-available
    type: boolean
    Provide this key with a value of true to indicate that new content is available. Including this key and value means that when your app is launched in the background or resumed, application:didReceiveRemoteNotification:fetchCompletionHandler: is called. (Newsstand apps are guaranteed to be able to receive at least one push with this key per 24-hour window). The Push API will translate the value of this field to 1 or 0 before sending it to APNS.

  • title
    type: string
    A short string describing the purpose of the notification. This field was introduced on Apple Watch but is also displayed on iOS devices as of iOS version 10.0. This key was added in iOS 8.2.

  • body
    type: string
    The text of the alert message.

  • title-loc-key
    type: string or null
    The key to a title string in the “Localizable.strings” file for the current localization. The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in the title-loc-args array. See Localized Formatted Strings for more information. This key was added in iOS 8.2.

  • title-loc-args
    type: array of strings or null
    Variable string values to appear in place of the format specifiers in title-loc-key. See Localized Formatted Strings for more information. This key was added in iOS 8.2.

  • action-loc-key
    type: string or null
    If a string is specified, the system displays an alert that includes the Close and View buttons. The string is used as a key to get a localized string in the current localization to use for the right button’s title instead of “View”. See Localized Formatted Strings for more information.

  • loc-key
    type: string
    A key to an alert-message string in a “Localizable.strings” file for the current localization (which is set by the user’s language preference). The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in the loc-args array. See Localized Formatted Strings for more information.

  • loc-args
    type: array of strings
    Variable string values to appear in place of the format specifiers in loc-key. See Localized Formatted Strings for more information.

  • launch-image
    type: string
    The filename of an image file in the app bundle; it may include the extension or omit it. The image is used as the launch image when users tap the action button or move the action slider. If this property is not specified then the system either uses the previous snapshot or uses the image identified by the UILaunchImageFile key in the app’s “Info.plist” file, or falls back to “Default.png”. This property was added in iOS 4.0.

Please check the Apple documentation for more detailed information.

Custom Fields for Android Pushes

The custom fields for android are a dictionary that can contain any fields required by your application. You can also specify a collapse_key in the custom fields for Android. A message with a collapse_key that has not yet been delivered may be replaced by a newer message with the same collapse key. Please see the Google documentation on collapsable messages.

Otherwise, you can specify any arbitrary freeform payload data to deliver to the receiving Android device. All of the fields in this in the android element in the push request will be supplied to the receiving Android device in the Bundle provided to onReceiveMessage method in the Android application’s subclass of GcmService. In general the push message data would be provided in a message JSON field but it is up to your application to use the message payload as it needs.

Note that the “message” → “body” field in the Push request body, if present, will be delivered in the “message” field of the GCM push notification payload.

Custom Fields for Other Platforms

Windows 8 (WNS)

See this reference for a description of Windows 8 push options. Note that PCF Push Notification Service support for Windows 8 is basic. Pivotal does not provide any up-to-date client SDKs for Windows 8 at this time.

Windows Phone (MPNS)

See this reference for a description of Windows Phone push options. Note that PCF Push Notification Service support for Windows 8 is basic. Pivotal does not provide any up-to-date client SDKs for Windows Phone at this time.

Complete Examples

Unlike the above examples, these examples will show the complete Push request body.

  • Send a message to all users subscribed to the “local_seminars” topics to alert them to an important community meeting. This message expires on the morning of Friday April 1, 2016.
{
  "message": {
    "body": "Town Hall This Thursday: Forging, Cheese, And You"
  },
  "target": {
    "topics": [ "local_seminars" ]
  },
  "expiryTime": 1459468800000
}
  • Send a push to all iOS and Android devices that are subscribed to one (or more) of the “breaking_news”, “local”, or “dairy” topics. Provide some custom fields that apps can use to deep link to article data. This message is scheduled to be delivered in two hours.
{
  "message": {
    "custom": {
      "ios": {
        "alert": {
          "body": "Breaking News: World's Biggest Cheese Forged At Local Bakery"
        },
        "content-available": true,
        "extra": { "story_url": "https://my_server/article/123456789" }
      },
      "android": {
        "message": "Breaking News: World's Biggest Cheese Forged At Local Bakery",
        "story_url": "https://my_server/article/123456789"
      }
      }
  },
  "target": {
    "topics": [ "breaking_news", "local", "dairy" ],
    "platforms": [ "ios", "android" ]
  },
  "scheduleIn": 7200
}
  • Send a push to one particular device informating the user that they have one new email notification. The badge on the app icon will be set to “1” and a sound will be played. Some of the email metadata is provided in the message extras so that the application can show a preview of the message. The message is given the “new_email” category so that iOS 8.0+ devices can provide appropriate action buttons for the user.
{
  "message": {
    "custom": {
      "ios": {
        "alert": {
          "body": "You've got mail!"
        },
        "category": "new_email",
        "badge": 1,
        "sound": "new_email",
        "content-available": true,
        "extra": {
          "from": "Your Local Bakery",
          "to": "You",
          "subject": "Special Deal on Cheese",
          "message_body": "Please come to your local bakery before Friday to sample a piece of the world's biggest cheese."
        }
      }
    }
  },
  "target": {
    "devices": [ "111-222-333444" ]
  }
}
  • All options in request body for pushing a message out to a list of devices or devices targeted by platform.
{
  "message": {
    "body": "Message body",                  # The text of the push message
    "custom": {
      "ios": {
        "alert": {
          "body": "iOS only message body",   # The body of the push message
          "action-loc-key": "actionKey",     # (overrides body defined above)
          "loc-key": "localizedStringKey",
          "loc-args": [ "arg1", "arg2", ... ],
          "title": "Title",
          "title-loc-key": "titleKey",
          "title-loc-args": [ "arg1", "arg2", ... ],
          "launch-image": "Default.png"
        },
        "category": "SAMPLE_CATEGORY",
        "badge": 1,
        "sound": "default",
        "content-available": true,           # Note - the Push API expects this field to be a boolean. (see below)
        "extra": {}
      },
      "android": {
        "collapse_key": "collapseKey"
      },
      "windows8": {
        "template_name": "TileSquareBlock",
        "template_fields": {
          "textField1":"text1",
          "textField2":"text2"
        },
        "options": {},
        "type": "tile"
      },
      "windowsPhone": {
        "template_fields": {
          "subtitle":"text",
          "parameter":"text"
        },
        "template": "toast"
      }
    }
  },
  "target": {
    "topics": [ "topic1", "topic2", ... ],
    "platforms": [ "platform1", "platform2", ... ],
    "devices": [ "device_uuid1", "device_uuid2", ... ],
    "interactive-only": false,     # Either true or false
    "platform": "all"              # One of the following options
  },                               # (ios, android, windows8, windowsPhone)

  "scheduleAt": 1345852800000,     # Epoch timestamp in milliseconds.
  "scheduleIn": 0,                 # Integer (time delta in seconds)
  "expiryTime": null               # Epoch timestamp in milliseconds.
}
Create a pull request or raise an issue on the source for this page in GitHub