Getting started with the Push API

The Localytics Push API currently exposes push as a single endpoint at https://messaging.localytics.com/v2/push/:app_id, which accepts the HTTP POST method.

POST /v2/push/:app_id

The payload is defined with a top level key of messages. Within messages is an array of one or more comma separated message objects.

You can send transactional messages to four types of user targets: audience_id, profile, customer_id, or broadcast. To locate the audience_id, export your audience files.

Here's an example of the general payload structure.

{ 
request_id: “1234-1234-1234-1234”, // Optional
campaign_key: null, // Required. Specify "null" if you don't want to use a campaign key.
target_type: "customer_id" // Replace with “customer_id” or "audience_id" or "profile" or
        "broadcast"
messages: [
            { 
              alert: "Mohana, your pizza is on its way!",
              target: "XYZ" // Replace with the customer ID, the audience ID, or { … profile rules… } 
              ios : {  // Optional block specific to iOS                             
                sound: "default.wav" // Optional                             
                badge: 1 // Optional                             
                extra: {} // Optional field for any custom key/value data that your app is configured to interpret                   
               }                         
               android : {  // Optional block specific to android                             
                  extra: {} // Optional field for any custom key/value data that your app is configured to interpret
                           }
          ]}

Here's an example of a payload targeting all users with specific profile information. You will need to specify the type of each profile attribute as a string, an integer, or a date. Dates should be formatted yyyy-mm-dd. You can use logical operators to join profile values based on the profile data type.

{   "profile": {
                criteria: [{         
                  key: "cats", // Profile key        
                  scope: "Organization"    // Profile scope: "LocalyticsApplication" or "Organization"
                  type: "string", // Data: "string", "int", or "date"  
                  op: "in", // Operator. Reference the table below for choices       
                  values: ["Ofelia", "Simba"] // Profile values        
                  }, 
                  <another criteria>],
              op: "and" // Outer operator for additional Profile attributes: "and" or "or           
              }
          }

Here's an example broadcast payload.

{ 
    request_id: “1234-1234-1234-1234”, // Optional  
    campaign_key: null, // Required, but specify null if you want no campaign key  
    target_type: "broadcast"
    messages: [                
        {               
          alert: “The Bruins win the Stanley Cup!"
        }
  ]
}

The following limits apply to data uploaded to the Localytics Push API:

• Customer IDs must be no longer than 128 characters, or 128 bytes.
• Rate limiting may be applied at more than 10 requests per second
• You may not batch more than 200 messages in a single API request
• Batching is currently only supported when targeting cusomter IDs