Trigger Push Message API - Based on Template ( Message for multiple end users)

 Please note that the following request should not be used to create a single message per a single end user. In order to create a single message per end user please use the direct API request format

The Trigger Push Message API based on template is used to send the following types of messages:

  • Push notifications - app-related, plain text notifications (as opposed to a Rich messages).  
  • All request data must be sent as an HTTP POST request in the JSON format.

The logic of using this API is as follows:

  • Create an "API Template Message" for all your triggers to be based on, by selecting the option as shown below
  • Copy the "Template ID" of the message, located in the summary page, to be used in the API request defined below
  • Use the API below to trigger messages over the API template message
  • The API request must include the schedule information for the specific trigger (as the template does not contain any schedule definition)
  • All fields in the trigger API calls you create from your server will override the definitions you entered in the template.
    For example: if you define sound in the template message and then wish to send a different sound in the trigger (in the API request), for the specific message sent the sound will be the one you entered in the request. The sound defined in the template message will remain the same.

 

 Appoxee API variables and parameters are case-sensitive.

Push Trigger Message Request

Request URL

POST

'http://saas.appoxee.com/api/v3/message'.

Request Header

The request header must include the following authentication parameters, used to log into Appoxee:

NameValue
X-ACCOUNT_CODE

Your Appoxee account code.

In case you don't have an account code add your Appoxee user name here as well

X-USERNAME

Your Appoxee user name.

X-PASSWORD

Your Appoxee password.

Request Body

Argument

 

Description

template_id

 

Mandatory

Specify the ID of this template message - please view above screenshot for details of how to obtain it

sound

Optional/Override

Specify the name of the sound to be played with the message.

To use the default sound file, set this argument to "default".

NOTE: If this argument is not specified in the payload, the message will have the sound defined in the template message.

push_body

Optional/Override

The message body displayed in the push notification.

push_badge

Optional/Override

The number displayed in the push notification badge. when not used no badge will be sent and the badge will remain the same on the device

NOTE: If this argument is not specified in the payload, the message will have the badge defined in the template message.

schedule_type

Mandatory

Specify when to send the notification:

  • 0 = send now
  • 1 = send according to each user's local time
  • 2 = send according to a specific time zone (defined in the "timzone" argument)
  • 4 = send according to user best time to send (must specify schedule date with this option)

timezone

Mandatory for Time Zone Schedules (schedule_type = 2)

Specify the timezone according to which this notification will be sent.

For example, to set the timezone to New York time, use the following syntax:

“America/New_York”

For a complete list of time zones, see Time Zones.

overdue

Mandatory for Local Schedules (schedule_type = 1)

Determines how to handle the notification in case it is overdue for the user's local time zone:

  • 0 = Send now
  • 1 = Do not send
  • 2 = Send the next day

schedule_date

Mandatory for Local, Time Zone and Best Time Schedules (schedule_type = 1 or 2 or 4)

The date and time on which to send this notification, specified in the UNIX time stamp format.

For example: 138490242

expire_date

Optional (By default, the message does NOT expire)

The date and time after which this notification expires and must not be sent (by default, a message does NOT expire).

If this property is enabled, you are required to specify the expiration date in the UNIX time stamp format.

For example: 138490242

Appoxee does not send expired messages. If a message sent by Appoxee expired before the user received it (for example, it the user's device was turned off during the relevant time frame), the Push notification service (APNS for iOS devices and GCM for Android devices) makes sure the expired message is not delivered.

expire_timezoneMandatory only when expire_date is set

Specify the timezone according to which this notification will expire.

For example, to set the timezone to New York time, use the following syntax:

“America/New_York”

For a complete list of time zones, see Time Zones.

segments

Optional

A segment groups app users based on different parameters.
You can use segments in Push notifications to target the relevant users out of all available users. 

Segments can include multiple parameters of different types:

  • Application-specific (Tags and Aliases)
  • Behavioral (such as "Last Activation" or "Number of products purchased")
  • Platform/Devices (such as SDK Version or App Version)
  • Regional Settings (Location, Language or Time Zone). 

You can either use existing segments, or create new ones.

To use an existing segment, send its ID. For example:

{ "segment_id": 243}

To create a new segment, you need to define the following attributes:

  • name
  • description
  • rules – each segment is defined by one or more rules. A rule consists of a field, an operator and an operand.

For a list of the available fields, see Segment Fields

For example:

{

     "name": "My Segment", "description": "My first segment",

      "rules": [

                      { "field": "appVersion", "operator": "=", "operand": [ "1" ] }

                    ]

 }

This code creates a new segment called “My Segment” that includes all users whose app version number is 1. 

For information on how to work with segments, see Using Segments / Creating Segment in the Push Message API.

NOTE: If this field is not included in the payload, the message is sent to all available users.

payloadOptional/Override
To add extra fields to a push message use this field as follows:
"payload" : {
                     "custom_key1":"custom_value1",
                     "custom_key2":"custom_value2",
     }
NOTE: If this argument is not specified in the payload, the message will have the extra fields defined in the template message.

Example Request

 

{
    "template_id": 32209,
    "push_body": "body",
    "push_badge": 1,
    "schedule_type": 2,
    "timezone": "Asia/Jerusalem",
    "overdue": 0,
    "schedule_date": 1345645282,
    "expire_date": 1645645282,
    "segments": [ // optional - can send the id of an existing segment or create a new one or both
        {
            "name": "My Segment",
            "description": "My first segment",
            "rules": [
                {
                    "field": "appVersion",
                    "operator": "=",
                    "operand": [
                        "android"
                    ],
                    "case_sensitive": 1
                },
                {
                    "field": "osNumber",
                    "operator": ">",
                    "operand": [
                        "3.0",
                        "2.0"
                    ]
                }
            ]
        },
        {
            "segment_id": 243
        }
    ],
    "payload": {
        "custom_key1": "custom_value1",
        "custom_key2": "custom_value2",
    }
}

 

{
	"template_id":32209,
    
    "schedule_type":0,
    "push_body": "Hi {FirstName-firstCap}, this is just for you",
    "payload":{"apx_dpl":"myapp://product/4", "banner":"1234"}
    
}


Response

HTTP Response Header

HTTP Header FieldValue
Status Code
  • Upon success – 200 OK 
  • Upon failure – the failure status code (for example: "400 Bad Request")

HTTP Response Body

The response body includes a description of the request result in JSON format. 
The API call has one of the following results:

Response ResultReturnsExample
metadata

Contains the "error" parameter:

  • If the Push message was sent successfully, the error value is "false"
  • Otherwise, the error value is "true"

{

    "error": "false"

}