Push notifications endpoints

Notifications

Sending a Layer message, announcement, or simply a Notification will deliver a push notification to all recipients. You can customize the notification contents and how it gets displayed when you send the message.

Standard Notifications

A standard notification may look like this:

{
  // ... other Message parameters
  "notification" : {
    "title": "Simon and Garfunkel",
    "text": "Hello darkness my old friend",
    "sound": "silence.aiff"
  }
}

This will send the same notification to all recipients. The title will be displayed on the lock screen or notification banner. On iOS, the text will also be displayed in the notification. On Android, the text will be sent as advisory information.

  • On iOS, the notification will also play the sound file “silence.aiff” if it exists in the main application bundle.
  • On Android, the sound is delivered as advisory information.
  • On Web, this notification data is not fully supported

User Customized Notifications

It’s possible to customize the notification for each recipient by specifying a value for the recipients key in the notification payload. These values will overwrite the default parameters at the root level of the notification payload; other recipients will simply receive the default parameters.

"notification" : {
  "title": "New Message",
  "text": "This is the alert text",
  "sound": "aaaaoooga.aiff",
  "recipients": [
    {
      "recipient": "layer:///identities/klaus_stube",
      "text": "hallo welt",
      "sound": "ping.aiff"
    },
    {
      "recipient": "layer:///identities/luigi_puccini",
      "title": "New Message",
      "text": "ciao mondo"
    },
    {
      "recipient": "layer:///identities/martina_marquez",
      "text": "hola mundo",
      "sound": "chime.aiff"
    },
    {
      "recipient": "layer:///identities/reginald_royford_williams_iii",
      "text": "Um.  Hello?"
    }
]
}

The following rules apply:

  • If sound, text or title is left out for a participant, they inherit from the default sound, text or title specified at the root of notification.
  • Participants not listed in the recipients section will get the default sound, text and title.
  • If there is no default sound, text or title, participants not listed in the recipients section will get a silent push and no notification.

Advanced push payload customization

You can send additional data in each push payload. The table below shows how Layer notification payloads map to APNS and GCM push keys:

Name APNS key GCM key
title title title
text body alert
sound sound sound
category category n/a
title-loc-key title-loc-key title_loc_key
title-loc-args title-loc-args title_loc_args
loc-key loc-key body_loc_key
loc-args loc-args body_loc_args
launch-image launch_image n/a
action-loc-key ??? ???
data data data

Documentation on push notification configuration can be found at the following links:

Method HTTP request Description
Send notification POST /apps/:app_uuid/notifications Send a notification to Android and iOS devices that is not associated with any Message or Conversation

Send notification

Send a notification to Android and iOS devices (web/mobile web not yet supported) that is not associated with any Message, Announcement or Conversation. The full structure of the notification object is identitcal to the structure used in sending Messages. See Advanced Notifications for more details.

Parameters:

Name Type Description
recipients string[] Array of Identity IDs to send the notification to
notification object See Notifications for details

HTTP request:

POST/apps/:app_uuid/notifications

Example:

{
    "recipients": [
        "layer:///identities/777",
        "layer:///identities/999"
    ],
    "notification": {
        "title": "New Alert",
        "text": "This is the alert text to include with the Push Notification.",
        "sound": "chime.aiff"
    }
}
curl -X POST \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/notifications\
 -d '{"recipients":["layer:///identities/777","layer:///identities/999"],"notification":{"title":"New Alert","text":"This is the alert text to include with the Push Notification.","sound":"chime.aiff"}}'

Possible responses:

Notification sent successfully
Status: 202 (Accepted)
(Empty body)

Discussion

Note

While we don’t impose a hard limit on the size of the recipients array, there is a limit of 1MB on the size of the request body posted to our servers. If you’re trying to send an announcement to a large number of your users, we recommend breaking it up into reasonably sized batches. If you see a 413 Request entity too large response, you’ll need to reduce the number of recipients you’re sending.