API Documentation for Push Notifications

Enhance your app capability by using Push Notifications service on IBM Cloud. This service enables you to send real-time notifications to mobile devices and web applications.

  • Notifications can be delivered to either all application users, or to a selected set of users or devices.
  • Supports both interactive and silent notifications.
  • Customers can choose to subscribe to specific tags or topics for notification.
  • Enables the app owner to analyze the number of devices that are registered to receive notifications and the number of notifications sent.

Get started by looking through our service documentation to understand the features and capabilities. It also has information on monitoring and troubleshooting aspects for any issues that you might come across.

The current document gives you detailed instructions on using our REST APIs. You can either use our SDK (software development kit) or REST (Representational State Transfer) API (application program interface) to further develop your client applications. Access the below Push Notifications Functions from your back-end server applications and the clients through Push REST APIs -

  • Push Configuration
  • Device registrations
  • Messages
  • Subscriptions
  • Tags
  • Webhooks

To access the Push REST APIs you will need a Base URL. A Base URL is dependent on the IBM Cloud region in which you have created your Push Notifications service.

To get a BASE URL, complete the following steps:

  • Follow the documentation to create a Push notification service instance. An App id is generated after creating a service instance.
  • Make a note of the Location in which the Push service instance is created.
  • Select one of the below Base URLs depending on the location in which your service instance is created

United Kingdom: https://imfpush.eu-gb.bluemix.net/imfpush/v1 Sydney: https://imfpush.au-syd.bluemix.net/imfpush/v1 Germany: https://imfpush.eu-de.bluemix.net/imfpush/v1 US South: https://imfpush.ng.bluemix.net/imfpush/v1 Washington: https://imfpush.us-east.bluemix.net/imfpush/v1

You may now use the Base URL in conjunction with the REST APIs to access the Push Notifications Functions

Methods

Retrieves all or a subset of existing device registration(s) of push.

Device registrations for the push service are retrieved for the specified criteria.

GET /apps/{applicationId}/devices
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

Query Parameters

  • Retrieves detailed information about the device

    Default: false

  • Pagination offset that is normally used along with the size

    • Note : Default offset is 0
  • Pagination size that is normally used along with the offset to retrieve a subset

    • Note : Default size is 100 and max size is 500
  • The filter has the following syntax: name operator expression . When you are using multiple filters, they can be combined by using AND and OR logic.

    • For AND logic, use multiple filters in the query.
    • For OR logic, use a comma(,) inside of the filter expression.
    • For both AND and OR logic: A single query can have both AND and OR logic. Each filter is evaluated individually before the filters are combined in an AND expression. For the Devices GET API the following combinations are supported: The name can be one of these fields: userId or platform
    • Except for the platform, the operator can be == or =@
    • For the platform, the operator must be == If operator =@ is used, the value can be a sub string.
    • If == is used, the value must be an exact matching string. Refer to the filter section for detailed syntax

    Constraints: collection format: multi

  • Retrieves device registrations only for the specified user.

Response

Status Code

  • Successfully retrieved the devices

  • One of the parameters provided in the input is incorrect.

  • The clientSecret header value did not match

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Creates a device registration

Creates a new device registration with the push service. The device registrations happens from the device. The deviceId is the unique ID for the device for the application.

POST /apps/{applicationId}/devices
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

The device information

Example:
Response

Status Code

  • Succesfully created device registration

  • The clientSecret header value did not match

  • The application doesn't exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • The application doesn't exist

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Retrieves report of devices registered

Device registrations report for the push service are retrieved for the specified criteria.

GET /apps/{applicationId}/devices/report
Request

Custom Headers

  • The appSecret associated with this application

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

Query Parameters

  • Number of days report has to be generated from

    • Note : Max value is 90
    • Min or default value is 1
Response

Status Code

  • Successfully retrieved Devices Report

  • The request was not understood by the push server. An invalid data in the input

  • Requires a valid appSecret header

Example responses

Deletes(unregisters) an existing device registration from the push service

Deletes device registrations for the given deviceID in the push service. When the device registration is successfully deleted, the call returns an HTTP response code 204 with no content.

DELETE /apps/{applicationId}/devices/{deviceId}
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

  • Unique device ID

Response

Status Code

  • Server successfully unregistered the device

  • The clientSecret header value did not match

  • The application or the device doesn't exist

  • An internal server error has occurred

Example responses

Retrieves an existing device registration of push

Device registrations for a push service that are retrieved for a specific deviceId.

GET /apps/{applicationId}/devices/{deviceId}
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Device deviceId to retrieve

  • Application unique ID for the push service

Response

Status Code

  • Retrieved detailed information about the device

  • The clientSecret header value did not match

  • The application or the device doesn't exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Update device registration

Updates push device registration with the new user ID or the specified token. In most use cases, only the userId is updated.

PUT /apps/{applicationId}/devices/{deviceId}
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

  • Unique device ID

The device information

Example:
Response

Status Code

  • Successfully updated the device registration

  • The clientSecret header value did not match

  • The application or the device doesn't exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Retrieve application settings

Retrieves the application settings, which is referenced by the applicationId parameter.

GET /apps/{applicationId}/settings
Request

Custom Headers

  • The appSecret associated with this application

  • The Authorization Token associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully retrieved the application settings.

  • The application referenced by the applicationId does not exist

  • Method Not Allowed

  • An internal server error has occurred

Example responses

Delete APNS settings

Deletes the APNS settings to the application referenced by the applicationId.

DELETE /apps/{applicationId}/settings/apnsConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with this application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Server successfully deleted the APNS credentials

  • The request was not understood by the push server. An invalid data in the input

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application does not exist

  • An internal server error has occurred

Example responses

Get the APNS settings

Retrieves APNS credentials for the application

GET /apps/{applicationId}/settings/apnsConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully retrieved APNS credentials

  • The request was not understood by the push server.

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • APNS configuration was not configured for the application mode.

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Updates APNS settings

Uploads an APNS certificate to the application referenced by the applicationId.

PUT /apps/{applicationId}/settings/apnsConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Form Parameters

  • Password for the APNS certificate

  • Type of the APNS certificate

  • The APNS certificate

Response

Status Code

  • Successfully updated the APNS certificate

  • The request was not understood by the push server. An invalid data in the input

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application or its credentials does not exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Delete GCM settings

Deletes the GCM credentials of the application, which is referenced by the applicationId parameter.

DELETE /apps/{applicationId}/settings/gcmConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully deleted the GCM credentials

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application does not exist

  • An internal server error has occurred

Example responses

Get the GCM settings

Retrieves GCM credentials for the application

GET /apps/{applicationId}/settings/gcmConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully retrieved GCM credentials

  • The request was not understood by the push server.

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • The GCM configuration was not found for the application.

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Updates GCM settings

Updates the GCM credentials of the application referenced by the applicationId.

PUT /apps/{applicationId}/settings/gcmConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

GCM credentials

Response

Status Code

  • Successfully updated the GCM credentials

  • The request was not understood by the push server. An invalid data in the input

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application does not exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Updates Safari Push Notifications settings

Uploads Safari Push Notifications settings to the application referenced by the applicationId. The settings include providing a web push certificate and other credentials. If none of the icons are provided then default icons will be used. These images populate the icons displayed to the user in the permission prompt, Notification Center and the notification itself.

PUT /apps/{applicationId}/settings/safariWebConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Form Parameters

  • Password for the web push certificate

  • The Safari web push certificate (p12 format)

  • The website name. This is the heading used in Notification Center

  • The URL to go to when the notification is clicked. Use %@ as a placeholder for arguments you fill in when delivering your notification. This URL must use the http or https scheme; otherwise, it is invalid.

  • Unique reverse-domain string for your Website Push ID such as web.com.example.domain (the string must start with web).

  • The URL of the website that should be permitted to subscribe to Safari Push Notifications.

  • PNG icon file of 16x16 size

  • PNG icon file of 16x16@2x size

  • PNG icon file of 32x32 size

  • PNG icon file of 32x32@2x size

  • PNG icon file of 128x128 size

  • PNG icon file of 128x128@2x size

Response

Status Code

  • Successfully updated the web push settings

  • The request was not understood by the push server. An invalid data in the input

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application or its credentials does not exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Get the Safari Push Notifications settings

Retrieves Safari Push Notifications settings for the application

GET /apps/{applicationId}/settings/safariWebConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully retrieved Safari WebPush credentials

  • The request was not understood by the push server.

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • The Safari Push Notifications settings was not found for the application

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Delete Safari Push Notifications settings

Deletes the Safari Push Notifications settings of the application, which is referenced by the applicationId parameter.

DELETE /apps/{applicationId}/settings/safariWebConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully deleted the Safari WebPush credentials

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application does not exist

  • An internal server error has occurred

Example responses

Get the GCM senderId

Retrieves GCM senderId only for the application.

GET /apps/{applicationId}/settings/gcmConfPublic
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Retrieved GCM senderId

  • The request was not understood by the push server.

  • The GCM configuration was not found for the application.

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Delete Chrome WebPush Settings

Deletes the Chrome WebPush credentials of the application, which is referenced by the applicationId parameter.

DELETE /apps/{applicationId}/settings/chromeWebConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully deleted the Chrome WebPush credentials

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application does not exist

  • An internal server error has occurred

Example responses

Get the Chrome WebPush settings

Retrieves Chrome WebPush credentials for the application

GET /apps/{applicationId}/settings/chromeWebConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully retrieved Chrome WebPush credentials

  • The request was not understood by the push server.

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • The Chrome WebPush configuration was not found for the application.

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Updates Chrome WebPush settings

Updates the Chrome WebPush credentials of the application referenced by the applicationId.

PUT /apps/{applicationId}/settings/chromeWebConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Chrome WebPush credentials

Response

Status Code

  • Successfully updated the Chrome WebPush credentials

  • The request was not understood by the push server. An invalid data in the input

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application does not exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Delete Firefox WebPush Settings

Deletes the Firefox WebPush credentials of the application, which is referenced by the applicationId parameter.

DELETE /apps/{applicationId}/settings/firefoxWebConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully deleted the Firefox WebPush credentials

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application does not exist

  • An internal server error has occurred

Example responses

Get the Firefox WebPush settings

Retrieves Firefox WebPush credentials for the application

GET /apps/{applicationId}/settings/firefoxWebConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully retrieved Firefox WebPush credentials

  • The request was not understood by the push server.

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • The Firefox WebPush configuration was not found for the application.

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Updates Firefox WebPush settings

Updates the Firefox WebPush credentials of the application referenced by the applicationId.

PUT /apps/{applicationId}/settings/firefoxWebConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Firefox WebPush credentials

Response

Status Code

  • Successfully updated the Chrome WebPush credentials

  • The request was not understood by the push server. An invalid data in the input

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application does not exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Delete Chorme Apps-Extentions Push credentials settings

Deletes the push credentials settings for Chrome Apps-Extensions of the application, which is referenced by the applicationId parameter.

DELETE /apps/{applicationId}/settings/chromeAppExtConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully deleted the Chorme Apps-Extentions Push credentials settings

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application does not exist

  • An internal server error has occurred

Example responses

Get the Chorme Apps-Extentions Push credentials settings

Retrieves Chorme Apps-Extentions Push credentials settings for the application

GET /apps/{applicationId}/settings/chromeAppExtConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully retrieved Chorme Apps-Extentions Push credentials credentials settings

  • The request was not understood by the push server.

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • The GCM configuration was not found for the application.

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Updates Chorme Apps-Extentions Push credentials settings

Updates the Chorme Apps-Extentions Push credentials settings of the application referenced by the applicationId.

PUT /apps/{applicationId}/settings/chromeAppExtConf
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Chorme Apps-Extentions Push credentials

Response

Status Code

  • Successfully updated the Chorme Apps-Extentions Push credentials settings

  • The request was not understood by the push server. An invalid data in the input

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • An application does not exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Get the GCM senderId for Chorme Apps-Extentions Push credentials

Retrieves GCM senderId only for Chorme Apps-Extentions Push credentials of the application.

GET /apps/{applicationId}/settings/chromeAppExtConfPublic
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

Response

Status Code

  • Successfully retrieved GCM senderId for Chorme Apps-Extentions Push credentials

  • The request was not understood by the push server.

  • The GCM configuration was not found for the application.

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Unsubscribes the speficied device from a tag

Subscriptions are uniquely identified by the combination of deviceId and tagName. Given the deviceId and the tag name, the request deletes a existing subscription from a tag specified. It will return HTTP response code 204 with no content on successfully unsubscribing

DELETE /apps/{applicationId}/subscriptions
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

Query Parameters

  • The tag name in the application

  • Unique ID of the device in the application

Response

Status Code

  • Successfully unsubscibed from the tag.

  • The request was not understood by the push server. An invalid data in the input

  • The clientSecret header value did not match

  • The tag, device or the application does not exist.

  • An internal server error has occurred

Example responses

Retrieves all or a subset of existing subscriptions

Retrieves subscriptions for the push service for the specified criteria.

GET /apps/{applicationId}/subscriptions
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

Query Parameters

  • Retrieves additional subscription details

    Default: false

  • Retrieves subscriptions only for the specified deviceId

  • Retrieves subscriptions only for the specified userId

  • Retrieves subscriptions only for the specified tagName

  • Pagination offset that is normally used along with the size

    • Note : Default offset is 0
  • Pagination size that is normally used along with the offset to retrieve a subset

    • Note : Default size is 100 and max size is 500
  • The filter has the following syntax: name operator expression . When you are using multiple filters, they can be combined by using AND and OR logic.

    • For AND logic, use multiple filters in the query.
    • For OR logic, use a comma(,) inside of the filter expression.
    • For both AND and OR logic: A single query can have both AND and OR logic. Each filter is evaluated individually before the filters are combined in an AND expression. For the subscription GET API the following combinations are supported:
    • The name can be one of these fields: tagName or deviceId
    • Except for the platform, the operator can be == or =@
    • For the platform, the operator must be ==
    • If the =@ operator is used, the value can be a sub string. If the == operator is used, the value must be an exact matching string. Refer to the filter section for detailed syntax

    Constraints: collection format: multi

Response

Status Code

  • Successfully retrieved the subscriptions

  • The clientSecret header value did not match

  • The application or the device doesn't exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Creates a new subscription for a tag.

Subscriptions are uniquely identified by the combination of deviceId and tagName. Using the deviceId and the tag name, the request creates a new subscription that subscribes the device to the specified tag. Both the device and tag resource must be created before using this API. Additionally an action=delete query parameter is provided to unsubscribe a list of tags from the specified device.

POST /apps/{applicationId}/subscriptions
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

Example:
Response

Status Code

  • Successfully created subscription

  • The clientSecret header value did not match

  • A device registraion with the specified deviceId is not found or the application is not found.

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Get tags

Retrieves all or a subset of tags in the application

GET /apps/{applicationId}/tags
Request

Custom Headers

  • The appSecret associated with this application

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

Query Parameters

  • Retrieves additional tag details

    Default: false

  • Pagination offset that is normally used along with the size

    • Note : Default offset is 0
  • Pagination size that is normally used along with the offset to retrieve a subset

    • Note : Default size is 100 and max size is 500
  • Retrieves the number of subscriptions for each platform if set to true

  • The filter has the following syntax: name operator expression . When you are using multiple filters, they can be combined by using AND and OR logic.

    • For AND logic, use multiple filters in the query.
    • For OR logic, use a comma(,) inside of the filter expression.
    • For both AND and OR logic: A single query can have both AND and OR logic. Each filter is evaluated individually before the filters are combined in an AND expression. For the Tag GET API the following combinations are supported:
    • The name can be one of these fields : tagame or description
    • If operator =@ is used, the value can be a sub string.
    • If == is used, the value must be an exact matching string. Refer to the filter section for detailed syntax

    Constraints: collection format: multi

Response

Status Code

  • Successfully retrieved tags

  • The request was not understood by the push server.

  • The appSecret header value did not match

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Creates a tag

Creates a tag with the unique name in the application, which is referenced by the applicationId parameter. The tag has associated with a description about the tag. The tag name cannot be updated after it is created

POST /apps/{applicationId}/tags
Request

Custom Headers

  • The application secret

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

Definition of the request to create tag

Example:
Response

Status Code

  • Successfully created tag

  • The request was not understood by the push server. An invalid JSON or an incorrect applicationId could result in this error code

  • Unauthorized - The application secret is incorrect

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • A tag with the specified applicationId already exits

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Delete tag

Delete the tag in the application.

DELETE /apps/{applicationId}/tags/{tagName}
Request

Custom Headers

  • The application secret

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

  • Unique ID of the tag for the push service

Response

Status Code

  • Successfully deleted the tag.

  • The request was not understood by the push server. An invalid data in the input

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • The tag referenced by the tagName does not exist

  • An internal server error has occurred

Example responses

Retrieve detailed tag information

Retrieves spcified tag in the application

GET /apps/{applicationId}/tags/{tagName}
Request

Custom Headers

  • The appSecret associated with this application

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

  • Unique ID of the tag in application

Response

Status Code

  • Successfully retrieved tag details

  • The request was not understood by the push server.

  • The appSecret header value did not match

  • Application or the tag was not found.

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Updates tag information

Updates the tag referenced by the tagName of the application referenced by the applicationId.

PUT /apps/{applicationId}/tags/{tagName}
Request

Custom Headers

  • The application secret

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

  • Unique ID of the tag

Definition of the request to update the tag

Example:
Response

Status Code

  • Successfully updated the tag

  • Push server did not understand request. Invalid JSON can cause this.

  • Unauthorized - The caller is either not authenticated or not authorized to make this request.

  • Application or tag does not exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Get all or subset of webhooks of the application.

Get all or subset of webhooks of the application. Webhooks allow you to build or set up integrations which subscribe to certain events on Push Notification service.

GET /apps/{applicationId}/webhooks
Request

Custom Headers

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • The identifier of the application

Response

Status Code

  • Retrieved all or a subset of Webhooks.

  • The caller is either not authenticated or ApplicationId not exists

  • Insufficient Scope

  • The application referenced by the applicationId does not exist

  • An internal server error has occurred

Example responses

Create a webhook

Creates a webhook with a unique name for the application, which is referenced by the applicationId parameter.

Subscribers of webhook events will receive alerts as JSON. For Sample event structure Refer to the Webhook section for detailed example

POST /apps/{applicationId}/webhooks
Request

Custom Headers

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • The identifier of the application

The request payload

Response

Status Code

  • Webhook created

  • The request was not understood by the push server. An invalid data in the input

  • The caller is either not authenticated or ApplicationId not exists

  • Insufficient Scope

  • A WebHook with the specified applicationId already exits

  • An internal server error has occurred

Example responses

Get the webhook details

Get the webhook details.

GET /apps/{applicationId}/webhooks/{webhookName}
Request

Custom Headers

  • The Authorization Token associated with the application

  • The application secret

Path Parameters

  • The identifier of the application

  • The name of the webhook

Response

Status Code

  • Webhook retrieved

  • The caller is either not authenticated or ApplicationId not exists

  • Insufficient Scope

  • The Webhook referenced by the applicationId does not exist

  • An internal server error has occurred

Example responses

Update the webhook information

Update the information for existing webhookName

PUT /apps/{applicationId}/webhooks/{webhookName}
Request

Custom Headers

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • The identifier of the application

  • The name of the webhook

The request payload

Response

Status Code

  • Updated webhook

  • The request was not understood by the push server. An invalid data in the input

  • The caller is either not authenticated or ApplicationId not exists

  • Insufficient Scope

  • Cannot update - The webhook referenced by the applicationId does not exist

  • An internal server error has occurred

Example responses

Delete the webhook

Delete the webhook.which is referenced by the WebhookName parameter.

DELETE /apps/{applicationId}/webhooks/{webhookName}
Request

Custom Headers

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • The identifier of the application

  • The name of the webhook

Response

Status Code

  • OK

  • The caller is either not authenticated or ApplicationId not exists

  • Insufficient Scope

  • The WebhookName referenced does not exist

  • An internal server error has occurred

Example responses

Send message with different options.

When the request to send the message is accepted, sends push notifications to the specified targets and returns HTTP return code 202. The sent messages are stored and would auto expire in 10 days. You would not be able to retrieve information about a message using GET, after this specified time limit.

POST /apps/{applicationId}/messages
Request

Custom Headers

  • The application secret

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

Target value can be deviceIds or userIds but not both

Example:
Response

Status Code

  • Accepted the request to send message

  • Unauthorized - The application secret is incorrect

  • Application doesn't exist

  • Method Not Allowed

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Retrieves a list of messages

Gets a list of messages.

GET /apps/{applicationId}/messages
Request

Custom Headers

  • The appSecret associated with this application

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

Query Parameters

  • Pagination offset that is normally used along with the size

    • Note : Default offset is 0
Response

Status Code

  • Retrieved list of messges

  • Requires a valid appSecret header

No Sample Response

This method does not specify any sample responses.

Send Bulk Messages

Send bulk messages with different options to be specified. The sent messages are stored and would auto expire in 10 days. You would not be able to retrieve information about a message using GET, after this specified time limit.

POST /apps/{applicationId}/messages/bulk
Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • The application secret

  • The Authorization Token associated with the application

Path Parameters

  • Application ID

Response

Status Code

  • Accepted the request to send message

  • Unauthorized - The application secret is incorrect.

  • Application does not exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • Unsupported Media Type - The content type specified in Content-Type header is not application/json.

  • An internal server error has occurred

Example responses

Retrieves report of Messages sent

Gets the report for the messages sent .

GET /apps/{applicationId}/messages/report
Request

Custom Headers

  • The appSecret associated with this application

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

Query Parameters

  • Number of days report has to be generated from

    • Note : Max value is 90
    • Min or default value is 1
Response

Status Code

  • Successfully retrieved Message Report

  • The request was not understood by the push server. An invalid data in the input

  • Requires a valid appSecret header

Example responses

Delete Message

Deletes a message identified by its messageId.

DELETE /apps/{applicationId}/messages/{messageId}
Request

Custom Headers

  • The appSecret associated with this application

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

  • Message ID

Response

Status Code

  • The message has been deleted successfully

  • Application does not exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Get Message

Retrieves information about a message identified by its messageId.

GET /apps/{applicationId}/messages/{messageId}
Request

Custom Headers

  • The appSecret associated with this application

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

  • Message ID

Response

Status Code

  • Information about the message that is retrieved

  • Application does not exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Retrieves status of a particular MessageId

Gets the status for a particular messageId .

GET /apps/{applicationId}/messages/{messageId}/status
Request

Custom Headers

  • The appSecret associated with this application

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

  • Message ID

Response

Status Code

  • Successfully retrieved Message Status

  • Requires a valid appSecret header

No Sample Response

This method does not specify any sample responses.

Retrieves report of a particular MessageId

Gets the report for a particular messageId .

GET /apps/{applicationId}/messages/{messageId}/report
Request

Custom Headers

  • The appSecret associated with this application

  • The Authorization Token associated with the application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

  • Message ID

Response

Status Code

  • Successfully retrieved Message Report

  • Requires a valid appSecret header

No Sample Response

This method does not specify any sample responses.

Retrieves device status of a particular MessageId

Retrieves status information for a device id about a message identified by its messageId.

GET /apps/{applicationId}/messages/{messageId}/deliverystatus
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

  • Message ID

Query Parameters

  • Device ID

    • Note : Device ID or User ID is required
  • User ID

    • Note : Device ID or User ID is required
Response

Status Code

  • Information about the message that is retrieved

  • Application does not exist

  • Unsupported Accept type - The media type specified in the Accept header is not set to 'application/json'.

  • An internal server error has occurred

Example responses

Update device status of a particular MessageId

Update device status of a particular MessageId

PUT /apps/{applicationId}/messages/{messageId}/deliverystatus
Request

Custom Headers

  • The clientSecret associated with this application

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Application ID

  • Message ID

Message Staus

Example:
Response

Status Code

  • Accepted the request to update the message status

  • Invalid json values was provided

  • Application/MessageId does not exist

  • An internal server error has occurred

Example responses