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 level, that are received for the same request_id.

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, but cannot contain any spaces. 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) - specify the Customer ID 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, string or object) - specifies the push notification message to display on the end user's device. You may pass an empty string for silent push notifications. If you are passing a JSON object:
    • title (required, 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 (.png, .gif etc.) of the rich media attachment. This requires SDK v4+ and proper rich push support.
  • 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_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.

Limits

  • Customer IDs must not be longer than 128 single byte characters
  • Batching messages in one request is supported when targeting customer_id
  • You can send up to 100 new campaign_keys per app_id in a 24 hour period
  • Rate limiting may be applied based on the target_type
    • customer_id: 1000 requests per second
    • broadcast: 2 requests per minute
    • profile: 600 requests per hour
    • 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",
            "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!"
        }
    ]
}