Announcements endpoints

Method HTTP request Description
Send an announcement POST /apps/:app_uuid/announcements Send an announcement to a set of users

Send an announcement

Parameters:

Name Type Description
app_uuid string Your Layer App ID
recipients string[] Array of Identity IDs to send the announcement to
sender_id string Identity ID of the sender
parts MessagePart[] Array of message parts (see below)
parts.body string Text or base64-encoded data
parts.mime_type string MIME type describing the body
parts.encoding string Specify base64 if sending base64-encoded data
notification object See Notifications for details

HTTP request:

POST/apps/:app_uuid/announcements

Example:

{
    "recipients": [
        "layer:///identities/1234",
        "layer:///identities/5678"
    ],
    "sender_id": "layer:///identities/777",
    "parts": [
        {
            "body": "Hello, World!",
            "mime_type": "text/plain"
        }
    ],
    "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>/announcements\
 -d '{"recipients":["layer:///identities/1234","layer:///identities/5678"],"sender_id":"layer:///identities/777","parts":[{"body":"Hello, World!","mime_type":"text/plain"}],"notification":{"title":"New Alert","text":"This is the alert text to include with the Push Notification.","sound":"chime.aiff"}}'

Possible responses:

Announcement sent successfully | Status: 202 (Accepted)

{
    "id": "layer:///announcements/f3cc7b32-3c92-11e4-baad-164230d1df67",
    "url": "https://api.layer.com/apps/24f43c32-4d95-11e4-b3a2-0fd00000020d/announcements/f3cc7b32-3c92-11e4-baad-164230d1df67",
    "sent_at": "2014-09-15T04:44:47+00:00",
    "recipients": [
        "layer:///identities/1234",
        "layer:///identities/5678"
    ],
    "sender": BasicIdentity,
    "parts": [
        {
            "body": "Hello, World!",
            "mime_type": "text/plain"
        }
    ]
}

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.