This API enables App Server to create messages, query message state, etc.

Authorization Mechanism

The authentication of all the requests uses HTTP Basic Authentication. username is App ID , and password is Open API Secret. You can go to [Application] -> [Settings]-> [API Secrets] on our website to view them.

Frequently-used Response Status Code

  • 200 OK: Requested successfully. The response content is decided by the real API.

  • 400 Bad Request: Requested incorrectly or parameter absent. The detailed parameter name and the corresponding error information lie in the response body.

  • 401 Unauthorized: Authentication failed or the user has no permission to the request item.

  • 404 Not Found: Request path error or the resource requested has been deleted.

  • 500 Internal Server Error: Server error. Please try later or contact us.

  • 503 Service Unavailable: Server is under maintenance. Please try later or contact us.

Messages 

Set of Messages 

Create New Message
/v2/open/messages

A Message is composed of three parts:

  • content: The message content, including (rich) text, notification bar style, click action, additional information, and so forth, and overriding a particular service is also supported.

    As for service overriding, it means you can put the common content of various services in the outer layer while the unique content of a particular service under this service. For example:

    {
        "content": {
            "alert": "Hello, everyone!",
            "apns": {
                "alert": "Hello, iOS users!",
                // iOS 8.0+ supports this field
                "category": "NEW_MESSAGE_CATEGORY"
            }
        },
        ......
    }

    The content that is push out using apns will be Hello, iOS users! while that by other service (if configured) will be Hello, everyone!, which will be easy for you to push dirrent content for different platforms without creating multiple messages.

    This overriding way also applies to other common options, such as extra and ttl, but not to rich.

    The alert field under apns supports the Object type to be used for internationalization, and the setting of the field is the same as that in the Apple documentation. For more details, see Child properties of the alert property.

    category is used to set the response category. Popularly speaking, it’s to display a set of buttons, and clicking a button will trigger the response event that is bound; it is for the client to define multiple categories, and here to provide the unique ID of the category that is used. For more details on the usage, see Registering Your Actionable Notification Types.

  • target: Messages will be pushed to the target devices (users), which may be all(i.e., broadcast messages) or the users selected through aliases, tokens or filter.

    "target": {
        "tokens": [
            // apns token
            "e9bb11011dfc5a51f4ead79ac8309e3acc635dfea445b94545836ae0d6042bc3",
            // tps token
            "5593863e7b276ee41acfbabf",
            ...
        ]
    },

    Example with the userVars variant:

    {
        "content": {
            "alert": "Hello, %%name%%!",
            // %%var_name%%, the placeholder syntax of the user variable, also applies to additional information
            "extra": {
                "gender": "%%gender%%"
            }
    
        },
        "target": {
            // or tokens
            "aliases": [
                { "alias": "Aaron", "userVars": { "name": "Aaron", "gender": "male" } },
                { "alias": "Alice", "userVars": { "name": "Alice", "gender": "female" } }
            ]
        }
    }

    The Placeholder (like %%var_name%%) will be replaced by the User Variable of every device (user) itself, so each device (user) will receive its specific messages. For example, user Aaron will receive:

    {
        "content": {
            "alert": "Hello, Aaron!",
            "extra": {
                "gender": "male"
            }
        }
    }
  • trigger: When the messages should be pushed, and three types are supported at present, including now, scheduled and geoFences.

Note that a successful return of this API only indicates we have accepted this request but doesn't mean the push has been completed or the messages have been sent to all clients, and the real push process is asynchronous.

The following is a complete example.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        "content": {
            // The content shown in the notification bar
            "alert": "hello world!",
            "rich": {
                "body": "rich page html"
            },
            "title": "common title",
            // The additional information sent to the application
            "extra": {
                "key": "value"
            },
            // When pushing, if a device is offine, the maximum time duration of the messages that can be kept on servers, in minutes, only takes effect to apns, tps, huaweipush and mipush
            "ttl": 1440,
            // apns specific content, optional
            "apns": {
                "alert": "alert text for apns",
                // Used to set the subscript or superscript of an icon to prompt users for unread messages, and the badege property of a device will be updated for recording the device under certain circumstances
                // The corresponding number of unread messages. The value could be: 
                //   1. If not set, the subscript or superscript will not change; the badge of the device will not be updated
                //   2. Digits only  indicates the final badge, among which 0 means clearing the subscript or superscript; the badge of the device will be updated
                //   3. String “+?”, such as +2, means adding 2 on the original value of a device itself for the final badge; similarly, “-?” indicates how much is subtracted; if the value turns to be minus after subtraction, reset it as 0; the badge of the device will be updated         
                //   4. In a way of userVar, such as “%%badge%%”, the final badge is the value of the badge in each device userVar; the badge of the devide will not be updated
                // All the other formats, except this, will be regarded that the subscript or superscript is not set
                "badge": "10",
                // If the sound file specified is not found, the default notification sound of the system will be played; if this field is not used, the sound will not be played
                "sound": "the name of a sound file in the application bundle",
                "extra": {
                    "key": "value"
                },
                "ttl": 2880
            },
            // tps specific content, optional
            "tps": {
                "alert": "alert text for tps",
                // The style of the notification bar utilizes 3-digit character of 01 to indicate whether to 'disable' ('0') or 'enable' ('1') the ring. Vibration and notification cannot be cleared
                "style": "110",
                // The Click action has three forms like below:
                //   '0': Launch the application, which is a default setting
                //   '1|package name': Launch other applications
                //   '2|url': Open a web page
                "action": "2|www.tuisongbao.com",
                "extra": {
                    "key": "value"
                },
                "ttl": 2880
            },
            // huaweipush specific content, optional
            "huaweipush": {
                "alert": "alert text for huaweipush",
                // The default value is set in the portal through [Application]-> [Settings]-> [Services]
                "title": "alert title for huaweipush",
                // 0 by default, indicating no passthrough, messages will be directly shown on the notification bar
                "passThrough": 1,
                "extra": {
                    "key": "value"
                },
                "ttl": 2880
            },
            // mipush specific content, optional
            "mipush": {
                "alert": "alert text for mipush",
                // The default value is set in the portal through [Application]-> [Settings]-> [Services]
                "title": "alert title for mipush",
                // 0 by default, indicating no passthrough, messages will be directly shown on the notification bar
                "passThrough": 1,
                // ALL = -1(default); SOUND  = 1; VIBRATE = 2; LIGHTS = 4; or free combination of these (except ALL),
                // For instance, set VIBRATE + LIGHTS = 2 + 4 = 6 instead of Sound if not needed, which also applies to others
                "notifyType": 2,
                "extra": {
                    "key": "value"
                },
                "ttl": 2880
            },
            // mpns specific content, optional
            "mpns": {
                "title": "alert title for mpns",
                "param": "/MainPage.xaml?key=value"
             }
        },
    
        "target": {
            // Services to be used
            //   All the services configured are used by default
            //   When selecting target users using aliases or tokens, services will be automatically populated
            "services": ['ad', 'ap', 'tps', 'huaweipush', 'mipush'],
            // Broadcast
            "all": true
            // Push by aliases, and all the devices with specified aliases will be pushed
            "aliases": ['s3', 's4'],
            // Push by tokens
            "tokens": ["53a53fbc4121f6b98ae37df7fbf0388ccb855a8a0184a2fab3261b6f20c2801c", "5315b2a69a0bc26f70195142"],
            // Use filters
            "filter": {
                "tags": ["hobbyMovie", "hobbySport"],
                // Every element indicates a location, represented by its complete administrative divisions, which are separated with comma by rank from high to low
                "locations": ["Shanghai, Shanghai, Pudong New District"],
                "appVersions": ["1.1"],
                // The time the application is last launched, in ISO 8601 format
                "inactiveSince": "2014-05-30T00:00:00.000Z"
            }
        },
    
        "trigger": {
            // Push immediately
            "now": true,
            // Set a future time to push messages, in ISO 8601 format
            "scheduled": "2014-06-30T10:30:00.000Z",
            "geoFences": {
                // Use all the geo-fences
                "allFences": false,
                // Use specific geo-fence, and if to use all, i.e., when the allFences field is true, this field should be null
                "fences": ["5315f91a9a0bc26f70150301"],
                "frequency": "every|once",
                "event": "enter|leave|enterOrLeave",
                "startTime": "2014-06-30T10:30:00.000Z",
                "endTime": "2014-07-01T10:30:00.000Z"
            }
        }
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
        // Create message ID, which can be used to query message state
        "id": "5315b2a69a0bc26f70130605"
    }

Devices 

Invalid Device Collections 

Query Invalid Devices
/v2/open/invalidDevices{?cursor,limit}

Different services have different mechanisms to detect the invalid devices: The application has been uninstalled, users set not to receive messages any more, and so forth. These devices will be kept on server for a week, and later will be removed entirely.

The 3rd-party application servers can regularly query the invalid devices through this API to prevent a repetitive sending to invalid devices while pushing by token or alias.

While using this API, invocations should be repeatedly made according to cursor till the result set returned is Null (count is 0) so as to get all the invalid devices currently. One query per day is suggested, and the newest cursor obtanined through a query made one day before should continue to be used one day after.

Currently, only the ad and ap service can detect users’ uninstallation behaviors and generate invalid devices.

  • Parameters
  • cursor
    string (optional) 

    The query start point, the value of which is null for the first invocation, and use the return value cursor of the last invocation for later invocation.

    limit
    integer (optional) Default: 20 

    How many records are returned, and the maximum value is 1000.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
        "count": 1,
        "cursor": "561797e41158ff2d5ca6a4f1",
        "list:" [{
            "service": "ad",
            "token": "555c4525ccd80f2a49330c6d",
            "alias": "aaron",
            "sdkVersion": "v1.0",
            "tags": ["aaron"],
            "location": "Shanghai, Shanghai, Pudong New District",
            "lastLoginAt": "2014 06/06 10:00",
            "userVars": {}
        }]
    }
  Back To Top