Push API

The Push API is an interface for sending real-time push notifications that leverages the Localytics marketing platform. The below reference will help you understand general usage of the Push API.

Getting Started

If you have not yet integrated the Localytics SDK into your app, or have not set up your app to receive push notifications using Localytics, please begin at our push integration guides for iOS or Android before proceeding.

The Push API exposes a single endpoint, which accepts the HTTP method POST, at:

POST https://messaging.localytics.com/v2/push/<app_id>

Replace <app_id> with your App ID, which can be found on the settings screen of your dashboard.

Authentication

The Push API authenticates users with a combination of your Push API key and Push API secret, both of which can be found on the Settings screen of the dashboard. These parameters may be passed to the API using HTTP Basic authentication. This is commonly known as "plain" or "gray box" authentication and is universally supported by HTTP clients. The API key is passed as the HTTP Basic username and the API secret is passed as the HTTP Basic password.

Responses and Errors

The Push API uses standard HTTP response codes, accompanied by descriptive response messages, to communicate success and error conditions to the client:

202: Accepted - Queued for delivery.

400: Bad Request - There is an issue with your request format, the response message will indicate what the specific error is.

401: Unauthorized - The API Key and API Secret are not valid.

403: Forbidden - There is an issue authorizing the use of the referenced app_id, audience_id, push certificate, and/or platform. The response message will indicate what the specific error is.

429: Too Many Requests - Depending on the given target_type, we may rate limit you requests. Limits are covered below.

Concepts

Request ID

request_id (optional, string) - specifies the unique request. Typically, you will send a GUID/UUID for this field. Localytics will automatically de-duplicate requests within 24 hours of each other, at the app_id + customer_id level, that are received for the same request_id. Maximum of 255 characters length.

Campaign Key

campaign_key (optional, string) - when included, generates a performance report for this request in your dashboard. Any request that references a previously used campaign_key will be rolled up into that existing performance report. If you do not want to generate a performance report, simply omit this key field from the payload.

The campaign_key is an arbitrary string up to 255 characters long, and can only include letters, numbers, or the characters _, -, or .. An editable campaign name can be applied in your dashboard after receiving performance data, but the campaign_key cannot change.

Important: you are limited to 100 new campaign_keys per app_id in a 24 hour period. It is recommended you omit campaign_key unless performance tracking is required.

Target Type

target_type (required, string) - specifies how you would like to target users. The four options are below:

  • broadcast - targets all users.
  • customer_id - targets individual users.
  • audience_id - targets users currently captured in the specified audience.
  • profile - targets users who currently match the specified profile attributes.

Targeting All Devices

all_devices (optional, boolean) - false by default, only available when targeting customer_id. If set to true, all known devices of the targeted user will receive the notification. If set to false, the default behavior will occur which will only send to the user's most recently active device.

Messages

messages (required, array of message Messages object)

  • target (required, except for broadcast campaigns) - specifies the targeting criteria depending on the target_type. The required criteria for each target_type is highlighted below:
    • broadcast - Not required.
    • customer_id (required, string or array of strings) - specify the Customer ID or a list of customer IDs you would like to target.
    • audience_id (required, int) - specify the Audience ID you would like to target.
      • To find the appropriate Audience ID, export your Audiences to CSV from your dashboard here.
    • profile (required, object) - specify the Profile Attributes you would like to target. The profile target type has required criteria that enables you to target specific profile attributes:
      • criteria (required, array of targeted profile object)
        • key (required, string) - specifies the key of the desired profile attribute you are targeting.
        • scope (required, string) - specifies the scope of the desired profile attribute. The two options are below:
          • LocalyticsApplication
          • Organization
        • type (required, string) - specifies the data type of the targeted profile attribute. The three supported types are below:
          • string
          • int
          • date
        • op (required, string)- specifies the inner operator for the targeted values. The supported types and their respective operators are below:
          • String type: in, not_in, is_null, is_not_null
          • Int type: <, >, <=, >=, in, between, not_in, is_null, is_not_null
          • Date type: <, >, <=, >=, in, between, not_in, is_null, is_not_null
        • op (required, string) - specifies the outer operator for the targeted profile attributes. The available operators are below:
          • and
          • or
  • alert (required, object) - specifies the push notification message to display on the end user's device. You may pass an empty string instead of an object for a silent push. If you are passing a JSON object:
    • title (optional, string) - a short string describing the purpose of the notification.
    • subtitle (optional, string) - a short string that expands on the title. This is only displayed for users running iOS 10 (and above).
    • body (required, string) - specifies the push notification's message.
  • ios (optional, object) - specifies platform specific functionality
    • sound (optional, string) - specifies the sound file in the app bundle or in the Library/Sounds folder of the app’s data container. If the sound file doesn’t exist or default is specified as the value, the default alert sound is played.
    • badge (optional, int) - specifies the unread badge number to display upon delivery.
    • category (optional, string) - specifies the category of actions (interactive push) to display to the user upon delivery.
    • content_available (optional, boolean) - True by default. Localytics utilizes content-available to enhance performance reports.
    • mutable_content (optional, boolean) - False by default. Setting it to true allows the alert to trigger Notification Extensions.
    • extra (optional, object) - key/value pairs to pass to the application in the push payload.
      • ll_deep_link_url (optional, string) - specifies the deeplink url. This requires SDK v4+ and deep linking is properly setup. Ensure the particular scheme/URL is registered and handled within your app.
      • ll_attachment_url (optional, string) - specifies the url of the rich media attachment. This requires SDK v4+ and proper rich push support.
      • ll_attachment_type (optional, string) - specifies the media type of the rich media attachment. This requires SDK v4+ and proper rich push support. Available options are gif, jpg, png, mp4, and mp3.
  • android (optional, object) - specifies platform specific functionality.
    • priority (optional, string) - specifies whether the notification should pre-emptively wake the device from Doze mode. This can be "high" or "normal"; if not passed the default behavior is the same as passing "normal". Overriding this is only recommended for time-sensitive messaging apps; for details see Google's documentation.
    • extra (optional, object) - key/value pairs to pass to the application in the push payload.
      • ll_channel (optional, string) - specifies the channel for the notification. If not set, the SDKs will use the configurable default channel.
      • ll_deep_link_url (optional, string) - specifies the deeplink url. This requires SDK v4+ and deep linking is properly setup. Ensure the particular scheme/URL is registered and handled within your app.
      • ll_attachment_url (optional, string) - specifies the url of the rich media attachment. This requires SDK v4.3+ for built in support. If you are using an earlier SDK please see our sample project to ensure proper setup. Android supports JPEG, PNG, and non-animated GIF files in rich push attachments.
      • ll_actions (optional, array of up to 3 objects) - specifies the actions that should be attached to this notification. This requires SDK v4.4+.
        • Array items must be objects with the following key/values:
        • title (required, string) - specifies the text that will be shown.
        • icon (optional, string) - specifies the name of the icon that will be shown adjacent to the title. Icons are only supported by Android N and lower. This icon must be located in your app's drawable resources.
        • deeplink (optional, string) - specifies the deeplink url. This requires deep linking is properly setup. Ensure the particular scheme/URL is registered and handled within your app.
  • web (optional, object) - specifies platform specific functionality. Not all keys will function on all browsers or all platforms. For a table of support, please visit our FAQs.
    • badge (optional, string) - A URL to an image which will be shown as the app icon on mobile devices. If none is specified, the browser's icon will be used.
    • dir (optional, string) - One of 'ltr', rtl' or 'auto'. This specifies the direction the text should be rendered on the device.
    • icon (optional, string) - A URL to an image which will be shown as a thumbnail on the notification.
    • requireInteraction (optional, boolean) - Specify if this notification must be interacted with to be dismissed. If this is set to true is will keep the notification visible on non-mobile devices. If set to false, the notification will dissapear into the notification drawer after a short period of time. The default is false.
    • renotify (optional, boolean) - Specify if this notification requires interaction. If this is an update to a previously sent notification, setting this value to true will ensure that the notification is displayed prominently again. The default is false.
    • silent (optional, boolean) - Specify if this notification should make noise or interrupt the user. Setting this value to true will deliver the notification directly to the notification drawer without sound and without alerting the user. The default is false.
    • extra (optional, object) - key/value pairs to pass to the application in the push payload.
      • ll_deep_link_url (optional, string) - specifies the deeplink url.
      • ll_attachment_url (optional, string) - specifies the url of the rich media attachment.
      • ll_actions (optional, array of up to 3 objects) - specifies the actions that should be attached to this notification. Array items must be objects with the following key/values:
        • title (required, string) - specifies the text that will be shown.
        • icon (optional, string) - specifies the url of the icon that will be shown adjacent to the title.
        • deeplink (optional, string) - specifies the deeplink url.

Labels

labels (optional, object) - key/value pairs that specify a set of optional labels associated with this request. These labels are intended to provide a finer level of granularity in measuring and analyzing campaign performance data than just campaign_key and request_id.

Up to 4 labels may be provided. The label keys must be named label1 through label4 respectively. The label values are stored as attributes on the Localytics Push Sent events recorded for each push notification sent from this request.

The labels are also passed to the application in the push payload within an object field named ll_push_event_attributes. The label keys inside this field are named Label 1 through Label 4. The SDK passes them back in the Localytics Push Received and Localytics Push Opened events sent from the app after receipt of the push notification.

In dashboard performance reports and Query API requests, these labels are available as custom attributes named Label 1 through Label 4 for each of these events.

Limits

  • Customer IDs must not be longer than 128 single byte characters
  • Batching messages in one request is supported when targeting customer_id
  • Each request's JSON must not exceed 100KB
  • You can send up to 100 new campaign_keys per app_id in a 24 hour period
  • campaign_key values must be 255 characters or less
  • request_id values must be 255 characters or less
  • Rate limiting may be applied based on the target_type
    • customer_id: 1000 requests per second
    • broadcast: 2 requests per minute
    • profile: 100 requests per 10-minute period
    • audience_id: 2 requests per minute

General Payload Structure Examples

Targeting a Customer ID

{  
    "request_id":"1234­1234­1234­1234",
    "target_type":"customer_id",
    "messages":[  
        {  
            "target":"user123",
            "alert":"Your pizza is ready!",
            "ios":{  
                "sound":"default.wav",
                "badge":1
            }
        }
    ]
}

Targeting multiple Customer IDs

{
"request_id":"1234­1234­1234­1234",
"target_type":"customer_id",
"messages":[
    {
        "target": ["user123", "user456", "user789"],
        "alert":"Use APRIL on your next order for 20% off",
        "ios":{
            "sound":"default.wav",
            "badge":1
        }
    }
]
}

Targeting multiple Customer IDs with different messages

{  
    "request_id":"1234­1234­1234­1234",
    "target_type":"customer_id",
    "messages":[  
        {  
            "target":"user123",
            "alert":"Use APRIL-123 on your next order for 20% off",
            "ios":{  
                "sound":"default.wav",
                "badge":1
            }
        },
        {  
            "target":"user456",
            "alert":"Use APRIL-456 on your next order for 10% off",
            "ios":{  
                "sound":"default.wav",
                "badge":1
            }
        }

    ]
}

Targeting an Audience ID

{  
    "request_id":"1234­1234­1234­1234",
    "target_type":"audience_id",
    "messages":[  
        {  
            "target":6804,
            "alert":{
                "title":"Message Title",
                "body": "Message Body!"
            },
            "ios":{  
                "sound":"default.wav",
                "badge":1
            }
        }
    ]
}

Targeting All Users

{  
    "request_id":"1234­1234­1234­1234",
    "target_type":"broadcast",
    "messages":[  
        {  
            "alert":"Free shipping on all orders!",
            "ios":{  
                "sound":"default.wav",
                "badge":1
            }
        }
    ]
}

Targeting Profile Attributes (with optional campaign_key set)

{  
    "request_id":"1234­1234­1234­1234",
    "campaign_key":"score_update",
    "target_type":"profile",
    "messages":[  
        {  
            "target":{  
                "profile":{  
                    "criteria":[  
                        {  
                            "key":"favorite_team",
                            "scope":"LocalyticsApplication",
                            "type":"string",
                            "op":"in",
                            "values":[  
                                "Red Sox"
                            ]
                        }
                    ],
                    "op":"and"
                }
            },
            "alert":"Your team just scored!"
        }
    ]
}

Targeting Profile Attributes (with optional labels specified)

{  
    "request_id":"1234123412341234",
    "campaign_key":"score_update",
    "target_type":"profile",
    "labels":{
        "label1":"score_alert",
        "label2":"Red Sox",
        "label3":"Yankees"
    },
    "messages":[
        {
            "target":{
                "profile":{
                    "criteria":[
                        {
                            "key":"favorite_team",
                            "scope":"LocalyticsApplication",
                            "type":"string",
                            "op":"in",
                            "values":[
                                "Red Sox"
                            ]
                        }
                    ],
                    "op":"and"
                }
            },
            "alert":"Your team just scored!"
        }
    ]
}