Push Message API

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

  • Push notifications - app-related, plain text notifications (as opposed to a Rich messages).  
    A Push notification is pushed to the device's screen, without the need to open the relevant application.
    Push notifications are used to inform the users of app-related events, such as content updates, new messages and other events that may interest them.
    Push notifications also allow the app to display a Badge on the app's icon (for example, the number of unread messages).
    Note that the user has the option to disable Push Notifications.
  • Rich message - app-related messages, whose content is rich (as opposed to a Push notification, whose content is plain text).  
    A Rich Message is used to engage the user with eye-catching content, such as YouTube videos, HTML messages etc.
    Rich Messages are sent to the in-app Inbox, so to enable such messages you must enable the Inbox feature (see Inbox).
    Note that users cannot disable Rich messages (as opposed to Push notifications, which users can choose to disable).

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



Request Header

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


Your Appoxee account code.

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


Your Appoxee user name.


Your Appoxee password.

Request Body






campaign_name & campaign_desc 


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



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.



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



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


Mandatory for Rich Messages (content_type=2 or 3)

The message title displayed in the inbox.


Mandatory for Rich Messages (content_type=2 or 3)

The message content displayed in the inbox.


Mandatory for Push Messages (content_type=1 or 3)

The message body displayed in the push notification.


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



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)


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:


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


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


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


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:


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


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



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.

To add extra fields to a push message use this field as follows:
"payload" : {

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,
	"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


    "name":"Test name",
    "description":"Test description",
    "push_body":"Test message (body)",
    	"name":"Segment A",
        "description":"My A segment",
        	{"field":"alias", "operator":"=", "operand":["66473138"]} ]  
    "payload":{"apx_dpl":"myapp://product/4", "banner":"1234"}


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

Contains the "error" parameter:

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


    "error": "false"



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:


           "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