The Push Message API is used to send the following types of messages:

All request data must be sent as an HTTPS POST request in the JSON format.

 Appoxee API variables and parameters are case-sensitive.

Push Message Request

Request URL

POST

'https://saas.appoxee.com/api/v3/message?finalize=1'.

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

campaign_id

OR

campaign_name & campaign_desc 

Mandatory

Specify the campaign this message belongs to in one of the following ways:

  • Specify the ID of an existing campaign, for example: "campaign_id": 1.
  • Create a new campaign now, by specifying the following details:
    • "campaign_name": "new campaign name",
    • "campaign_desc": "new campaign description"
application_idMandatoryApplication ID can be found in the dashboard - enter the app settings page and copy the suffix of the URL of that page - this is the application ID
nameMandatoryThe name of the message you are creating
descriptionMandatoryA description for the message you are creating

sound

Optional

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 no sound.

type

Mandatory

Specify the type of this message by entering one of the following values:

  • 0 = a "Broadcast" message, sent to all opted-in push users at once, across all platforms supported by your app.
    Broadcasts are commonly used to send "Breaking News" notifications, promotions etc.
  • 1 = a "Welcome" message, displayed the first time the user opens the app.
  • 3 = a "Periodic" message, sent according to a specific schedule.
    In this case, you are required to set the message frequency (see below).
frequencyMandatory for Periodic Messages (type=3)

If the message type is 3 (periodic), you are required to specify the notification frequency:

  • 0 = daily
  • 1 = Weekly
  • 2 = Monthly

For example, to send a periodic notification on a weekly basis, use the following arguments:

  • "type":3,
  • "frequency":1

content_type

Mandatory

The type of content included in this notification:

  • 1 = Push message only (text notification)
  • 2 = Rich message only (such as YouTube videos, HTML messages etc.)
  • 3 = Both push and rich messages

inbox_title

Mandatory for Rich Messages (content_type=2 or 3)

The message title displayed in the inbox.

inbox_description

Mandatory for Rich Messages (content_type=2 or 3)

The message content displayed in the inbox.

push_body

Mandatory for Push Messages (content_type=1 or 3)

The message body displayed in the push notification.

push_badge

Optional for Push Messages (content_type=1 or 3)

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

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 Schedules (schedule_type = 1 or 2)

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.

content_units

Mandatory for Rich Messages (content_type=2 or 3)

Defines the content of rich text messages as either text (HTML) or a link (URL).

This parameter must specify the content of all supported devices (listed in the Application Information page of your Appoxee account).

The devices are defined by their size:

  • Android devices:
    • android_small
    • android_medium
    • android_large
    • android_extra_large
  • iOS devices:
    • iphone4
    • iphone5
    • ipad

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
To add extra fields to a push message use this field as follows:
"payload" : {
                     "custom_key1":"custom_value1",
                     "custom_key2":"custom_value2",
     }

Example Request

 

{
	"campaign_id": 1 (existing campaign id),
	"application_id": 1,
	"sound": "",
	"name": "",
	"description": "",
	"type": 0,
	"content_type": 1,
	"inbox_title": "title",
	"inbox_description": "description",
	"push_body": "body",
	"push_badge": 1,
	"schedule_type":0,
	"timezone": "Asia/Jerusalem",
	"overdue": 0,
	"schedule_date": 1345645282,
	"expire_date" : 1645645282,
	"content_units": [
		{ "size": "iphone4", "body": "[html code]" },(second value is “body or “url”)
		{ "size": "iphone5", "url": "http://yahoo.com" }, (second value is “body or “url”)
		{ "size": "ipad", "url": "http://google.com" } (second value is “body or “url”)
	],
	"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": [ "2.44" ], "case_sensitive": 1 },
			{ "field": "osNumber", "operator": "=", "operand": [ "8.0", "8.01" ] }
		]
	},
    {
		"name": "Another Segment ", "description": "My first segment",
		"rules": [
			{ "field": "appVersion", "operator": "=", "operand": [ "2.44" ], "case_sensitive": 1 },
			{ "field": "osNumber", "operator": ">", "operand": [ "5.1" ] }
		]
	},
    {
		"segment_id": 243
	},
	{
		"segment_id": 319
	}
 ]
}

 

{
	"campaign_id":"161156",
    "application_id":"103012",
    "sound":"default",
    "name":"Test name",
    "description":"Test description",
    "type":0,
    "content_type":1,
    "push_body":"Test message (body)",
    "push_badge":1,
    "schedule_type":0,
    "segments":[
    {
    	"name":"Segment A",
        "description":"My A segment",
    	"rules":[
        	{"field":"alias", "operator":"=", "operand":["66473138"]} ]  
    }],
    "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"

}

payload

The properties of the new message object created by this Push request.

Use the "id" value to access the message object in the following location:

https://engage.appoxee.com/message/preview/{id}

       "payload":
       {
           "id": 2342857,
           "campaign_id": 148340,
           "application_id": 100264,
           "name": "Promotion",
           "description": "Users receive 50 points in the game once the return to the app.",
           "type": 0,
           "content_type": 1,
           "schedule_date": 0,
           "schedule_type": 0,
           "timezone": "",
           "overdue": 0,
           "inbox_title": "MyInbox",
           "inbox_description": "My application inbox",
           "push_body": "You have just received 50 points in the game! The points will added to your account the next time you launch the application.",
           "push_badge": 1,
           "expire_date": 0,
           "created": 1385048814
       }