Introduction

Enhance your app capability by using Push Notifications service on IBM Cloud 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 the service documentation to understand the features and capabilities. It also has information on SDKs, monitoring, and troubleshooting aspects for any issues that you might come across.

ReST APIs

The current document gives you detailed instructions on using the Push Notifications service ReST APIs. You can either use the SDK (Software Development Kit) or ReST (Representational State Transfer) API (application programming interface) to further develop your client applications. Access these Push Notifications functions from your back-end server applications and the clients through Push ReST APIs -

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

SDKs

Following are the list of Push Notifications Client SDKs and Server-side SDKs. For more information about installation and technical concepts, see the 'readme' document in the SDK.

To get the IAM accessToken, call the IBM Cloud IAM API with the Push Notifications service instance APIKey.

 curl -k -X POST --header "Content-Type: application/x-www-form-urlencoded" --header "Accept: application/json" --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" --data-urlencode "response_type=cloud_iam" --data-urlencode "apikey=<API-KEY>” "https://iam.cloud.ibm.com/identity/token"

Replace the API-KEY with the Push Notifications service instance APIKey.

The code examples on this tab use the IBM Cloud Push Notifications server library for Java.

Maven

<dependency>
    <groupId>com.ibm.mobilefirstplatform.serversdk.java</groupId>
    <artifactId>push</artifactId>
    <version>1.5.0</version>
</dependency>

Initialize SDK

import com.ibm.mobilefirstplatform.serversdk.java.push.PushNotifications;

// Initialize with AppSecret
PushNotifications.init("<PUSH-APPGUID>", "<PUSH-APPSECRET>", "<PUSH-REGION>"); 

//Initialize with ApiKey
PushNotifications.initWithApiKey("<PUSH-APPGUID>", "<PUSH-APIKEY>", "<PUSH-REGION>");

Get the PUSH-APPGUID , , and PUSH-APIKEY from the Push Notifications service instance's credentials section. Available PUSH-REGION are:

  • Dallas - PushNotifications.US_SOUTH_REGION
  • London - PushNotifications.UK_REGION
  • Sydney - PushNotifications.SYDNEY_REGION
  • Frankfurt - PushNotifications.FRANKFURT_REGION
  • Washington DC - PushNotifications.US_EAST_REGION
  • Tokyo - PushNotifications.JP_TOK

To know more about initialization follow this documentation.

GitHub

API Docs

The code examples on this tab use the IBM Cloud Push Notifications service Go SDK.

Installation

go get -u github.com/IBM/push-notifications-go-sdk

Example that initializes the SDK programmatically.

import (
    "github.com/IBM/go-sdk-core/v5/core"
    "github.com/IBM/push-notifications-go-sdk/pushservicev1"
)

func main() {

    pnClient, err := pushservicev1.NewPushServiceV1(&pushservicev1.PushServiceV1Options {
            URL: "{url}",
            Authenticator: &core.IamAuthenticator {
                ApiKey: "{apikey}",
            },
    })

    if err != nil {
            panic(err)
    }
}

Get the apikey and url from the Push Notifications service instance's credentials section.

To know more about initialization follow this documentation.

The code examples on this tab use the IBM Cloud Push Notifications server-side library for Node.

Installation

 npm install ibm-push-notifications --save

Initialize SDK


 var PushNotifications = require('ibm-push-notifications').PushNotifications;
 var Notification = require('ibm-push-notifications').Notification;
 var PushMessageBuilder = require('ibm-push-notifications').PushMessageBuilder;
 var PushNotificationsApiKey = require('ibm-push-notifications').PushNotificationsWithApiKey;

//Initialize with Appsecret 

 var myPushNotifications = new PushNotifications("<PUSH-REGION>", "<PUSH-APPGUID>", "<PUSH-APPSECRET>");

 //Initialize with ApiKey
 var myPushNotifications = new PushNotificationsApiKey("<PUSH-REGION>", "<PUSH-APPGUID>", "<PUSH-APIKEY");

 // Get authtoken
 myPushNotifications.getAuthToken(function(hastoken,token){
  console.log(hastoken, token);
 }

Get the PUSH-APPGUID , PUSH-APPSECRET and PUSH-APIKEY from the Push Notifications service instance's credentials section. Available PUSH-REGION are:

  • Dallas - PushNotifications.Region.US_SOUTH
  • London - PushNotifications.Region.UK
  • Sydney - PushNotifications.Region.SYDNEY
  • Frankfurt - PushNotifications.Region.FRANKFURT
  • Washington DC - PushNotifications.Region.US_EAST
  • Tokyo - PushNotifications.Region.JP_TOK

To know more about initialization follow this documentation.

GitHub

API Docs

The code examples on this tab use the IBM Cloud Push Notifications server-side library for swift.

Swift package

 import PackageDescription
 let package = Package(
    dependencies: [
        .package(url: "https://github.com/ibm-bluemix-mobile-services/bluemix-pushnotifications-swift-sdk.git", .upToNextMajor(from: "1.1.0"))
    ]
 )

Initialize SDK

import IBMPushNotifications

//Initialize with AppSecret
 let myPushNotifications = PushNotifications(pushRegion: "<PUSH-REGION>", pushAppGuid: "<PUSH-APPGUID>", pushAppSecret: "<PUSH-APPSECRET>")

//Initialize with ApiKey

let myPushNotifications = PushNotifications(pushApiKey:"<PUSH-APIKEY>", pushAppGuid: "<PUSH-APPGUID>", pushRegion: "<PUSH-REGION>")

 // GET AUTH TOKEN
 myPushNotifications?.getAuthToken(completionHandler: { (hasToken, tokenString) in
  if hasToken! {
    // Send push notifications
  }
 })

Get the PUSH-APPGUID , PUSH-APPSECRET and PUSH-APIKEY from the Push Notifications service instance's credentials section. Available PUSH-REGION are:

  • Dallas - PushNotifications.Region.US_SOUTH
  • London - PushNotifications.Region.UK
  • Sydney - PushNotifications.Region.SYDNEY
  • Frankfurt - PushNotifications.Region.FRANKFURT
  • Washington DC - PushNotifications.Region.US_EAST
  • Tokyo - PushNotifications.Region.JP_TOK

To know more about initialization follow this documentation.

GitHub

API Docs

Endpoint URLs

To access the Push ReST APIs, you need a Base URL. A Base URL depends on the IBM Cloud region in which your Push Notifications service is created.

To get a BASE URL, complete the following steps:

  • Follow the documentation to create a Push Notifications service instance. An App ID is generated after a service instance is created.
  • Make a note of the Location in which the Push Notifications service instance is created.
  • Select a Base URL depending on the location in which your service instance is created:
    • Dallas: http://us-south.imfpush.cloud.ibm.com/imfpush/v1
    • London: https://eu-gb.imfpush.cloud.ibm.com/imfpush/v1
    • Sydney: https://au-syd.imfpush.cloud.ibm.com/imfpush/v1
    • Frankfurt: https://eu-de.imfpush.cloud.ibm.com/imfpush/v1
    • Washington DC: https://us-east.imfpush.cloud.ibm.com/imfpush/v1
    • Tokyo: https://jp-tok.imfpush.cloud.ibm.com/imfpush/v1

You can now use the Base URL along with the ReST APIs to access the Push Notifications functions.

Authentication

Access to IBM Cloud Push Notifications service is controlled by using IBM Cloud® Identity and Access Management (IAM), which provides a unified approach to managing user identities, and access control across your IBM Cloud® services and applications.

To work with the API, authenticate your application or service by including your IBM Cloud® IAM access token in API requests.

Further information:

Event tracking

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called. An event is generated that you can then track and audit from within IBM Cloud Activity Tracker.

The specific event type is listed for each individual method. For more information about how to track activity, see Auditing Events for Push Notifications.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 2xx response always indicates success. A 4xx type response is some sort of failure, and a 5xx type response usually indicates an internal system error.

HTTP error code Description Recovery
200 Success The request was successful.
201 Success The resource was successfully created and added to your IBM Cloud account.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access the apps. Check that you have the correct access credentials and permissions.
404 Not Found The requested resource cannot be found.
408 Request timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The entity is already in the requested state.
429 Too Many Requests Too many requests made within a time window. Wait before calling the API again.
500 Internal Server Error IBM Cloud Push Notifications service is not available. Your request could not be processed. Wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
503 Service Temporarily Unavailable IBM Cloud Push Notifications might not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Versioning

API requests require a major version in the path (/v1/).

Methods

Retrieve application settings

Retrieves the application settings, which is referenced by the applicationId parameter. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/settings

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app.list

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "apnsConf": "http://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/1234/settings/apnsConf",
      "gcmConf": "http://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/1234/settings/gcmConf"
    }
  • {
      "code": "FPWSE0001E",
      "message": "Not Found - Targeted resource 'PushApplication' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Delete APNS settings

Deletes the APNS settings to the application referenced by the applicationId. This API is not available as a part of any frameworks. Use REST to utilise the feature.

DELETE /apps/{applicationId}/settings/apnsConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.delete

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-apns.delete

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with this application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request DELETE   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/apnsConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'PushEnvironment' does not exist. Check the 'Sample Application-ios' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get the APNS settings

Retrieves APNS credentials for the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/settings/apnsConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-apns.read

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/apnsConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "certificate": "apns-certificate-sandbox.p12",
      "isSandBox": true,
      "password": "*******",
      "validUntil": ""
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": "Not Found - Targeted resource 'Push APNS Configuration' does not exist. Check the 'UnknownApp' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Updates APNS settings

Uploads an APNS certificate to the application referenced by the applicationId. This API is not available as a part of any frameworks. Use REST to utilise the feature.

PUT /apps/{applicationId}/settings/apnsConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.update

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-apns.update

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Form Parameters

  • Type of the APNS certificate

  • The APNS certificate

  • Password for the APNS .p12 certificate (Required for .p12)

  • KeyID of the APNS .p8 Certificate (Required for .p8)

  • TeamID of the .p8 certificate dev account (Required for .p8)

  • BundleId of the application (Required for .p8)

  • curl --request PUT   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/apnsConf' 
      --header 'accept: application/json' 
      --header 'Content-Type: multipart/form-data' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
      -F password=<formData password> -F isSandBox=true -F certificate=<form data certificate blob> 
    

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
  • {
      "certificate": "apns-certificate-sandbox.p12",
      "isSandBox": true,
      "password": "*******",
      "validUntil": ""
    }
  • {
      "code": "FPWSE0005E",
      "message": "Invalid value was provided. Check the 'certificate' parameter value."
    }
  • {
      "code": "FPWSE0001E",
      "message": "Not Found - Targeted resource 'PushEnvironment' does not exist. Check the 'Sample-ios' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get the Web Push Server Key

Retrieves Web Push Server Key (VAPID). This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/settings/webpushServerKey

Request

Custom Headers

  • 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 server for the IBM Cloud Push Notification Service identification for web push communication

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/webpushServerKey' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

Response

Status Code

  • Retrieved Application Server Key

  • The request was not understood by the push server.

  • The Application Server key 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
  • {
      "webpushServerKey": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Delete GCM settings

Deletes the GCM credentials of the application, which is referenced by the applicationId parameter. This API is not available as a part of any frameworks. Use REST to utilise the feature.

DELETE /apps/{applicationId}/settings/gcmConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.delete

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-gcm.delete

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request DELETE   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/gcmConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get the GCM settings

Retrieves GCM credentials for the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/settings/gcmConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-gcm.read

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/gcmConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "apiKey": "string",
      "senderId": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'Push GCM Configuration' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Updates GCM settings

Updates the GCM credentials of the application referenced by the applicationId. This API is not available as a part of any frameworks. Use REST to utilise the feature.

PUT /apps/{applicationId}/settings/gcmConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.update

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-gcm.update

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

GCM credentials

Examples:
View
  • curl --request PUT   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/gcmConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
      --data '{"apiKey": <FCM_APIKEY>, "senderId": <FCM_SENDER_ID>}' 
    

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
  • {
      "apiKey": "string",
      "senderId": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": "Not Found - Targeted resource 'PushApplication' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

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. This API is not available as a part of any frameworks. Use REST to utilise the feature.

PUT /apps/{applicationId}/settings/safariWebConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.update

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-safari.update

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • 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 (Required for .p12)

  • The Safari web push certificate

  • 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

  • KeyID of the APNS .p8 Certificate (Required for .p8)

  • TeamID of the .p8 certificate dev account (Required for .p8)

  • BundleId of the application (Required for .p8)

  • curl --request PUT   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/safariWebConf' 
      --header 'accept: application/json' 
      --header 'Content-Type: multipart/form-data' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
      -F password=<formData password> -F certificate=<form data certificate blob> -F websiteName=<websiteName> -F urlFormatString=<urlFormatString> -F websitePushID=<websitePushID> -F webSiteUrl=<webSiteUrl>
    

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
  • {
      "certificate": "web-certificate.p12",
      "password": "*******",
      "websiteName": "Sample Website",
      "urlFormatString": "http://%@",
      "websitePushID": "web.com.example",
      "webSiteUrl": "https://example.com"
    }
  • {
      "code": "FPWSE0005E",
      "message": "Invalid value was provided. Check the 'certificate' parameter value."
    }
  • {
      "code": "FPWSE0001E",
      "message": "Not Found - Targeted resource 'PushEnvironment' does not exist. Check the 'Sample-ios' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get the Safari Push Notifications settings

Retrieves Safari Push Notifications settings for the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/settings/safariWebConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-safari.read

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/safariWebConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "certificate": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'Push Safari Web Push Configuration' does not exist."
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Delete Safari Push Notifications settings

Deletes the Safari Push Notifications settings of the application, which is referenced by the applicationId parameter. This API is not available as a part of any frameworks. Use REST to utilise the feature.

DELETE /apps/{applicationId}/settings/safariWebConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.delete

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-safari.delete

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request DELETE   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/safariWebConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get the GCM senderId

Retrieves GCM senderId only for the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/settings/gcmConfPublic

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-gcm.read

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/gcmConfPublic' 
      --header 'accept: application/json' 
    

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
  • {
      "senderId": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'Push GCM Configuration' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Delete Chrome WebPush Settings

Deletes the Chrome WebPush credentials of the application, which is referenced by the applicationId parameter. This API is not available as a part of any frameworks. Use REST to utilise the feature.

DELETE /apps/{applicationId}/settings/chromeWebConf

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request DELETE   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/chromeWebConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get the Chrome WebPush settings

Retrieves Chrome WebPush credentials for the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/settings/chromeWebConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-chrome.read

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/chromeWebConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "apiKey": "string",
      "webSiteUrl": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'Chrome WebPush Configuration' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Updates Chrome WebPush settings

Updates the Chrome WebPush credentials of the application referenced by the applicationId. This API is not available as a part of any frameworks. Use REST to utilise the feature.

PUT /apps/{applicationId}/settings/chromeWebConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.update

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-chrome.update

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Chrome WebPush credentials

Examples:
View
  • curl --request PUT   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/chromeWebConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
      --data '{"apiKey": <FCM_APIKEY>, "webSiteUrl": <WEBSITE_URL>}' 
    

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
  • {
      "apiKey": "string",
      "webSiteUrl": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Delete Firefox WebPush Settings

Deletes the Firefox WebPush credentials of the application, which is referenced by the applicationId parameter. This API is not available as a part of any frameworks. Use REST to utilise the feature.

DELETE /apps/{applicationId}/settings/firefoxWebConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.delete

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-firefox.delete

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request DELETE   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/firefoxWebConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get the Firefox WebPush settings

Retrieves Firefox WebPush credentials for the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/settings/firefoxWebConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-firefox.read

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/firefoxWebConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "webSiteUrl": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'Firefox WebPush Configuration' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Updates Firefox WebPush settings

Updates the Firefox WebPush credentials of the application referenced by the applicationId. This API is not available as a part of any frameworks. Use REST to utilise the feature.

PUT /apps/{applicationId}/settings/firefoxWebConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.update

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-firefox.update

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Firefox WebPush credentials

Examples:
View
  • curl --request PUT   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/firefoxWebConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
      --data '{"webSiteUrl": <WEBSITE_URL>}' 
    

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
  • {
      "webSiteUrl": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

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. This API is not available as a part of any frameworks. Use REST to utilise the feature.

DELETE /apps/{applicationId}/settings/chromeAppExtConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.delete

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-chromeapp.delete

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request DELETE   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/chromeAppExtConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get the Chorme Apps-Extentions Push credentials settings

Retrieves Chorme Apps-Extentions Push credentials settings for the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/settings/chromeAppExtConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-chromeapp.read

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/chromeAppExtConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "apiKey": "string",
      "senderId": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'Push GCM Configuration' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Updates Chorme Apps-Extentions Push credentials settings

Updates the Chorme Apps-Extentions Push credentials settings of the application referenced by the applicationId. This API is not available as a part of any frameworks. Use REST to utilise the feature.

PUT /apps/{applicationId}/settings/chromeAppExtConf

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.update

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-chromeapp.update

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

  • Deprecated, use Authorization instead.

  • The Authorization Token associated with the application

Path Parameters

  • Unique ID of the application using the push service

Chorme Apps-Extentions Push credentials

Examples:
View
  • curl --request PUT   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/chromeAppExtConf' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
      --data '{"apiKey": <FCM_API_KEY>,"senderId": <FCM_SENDER_ID>}' 
    

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
  • {
      "apiKey": "string",
      "senderId": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get the GCM senderId for Chorme Apps-Extentions Push credentials

Retrieves GCM senderId only for Chorme Apps-Extentions Push credentials of the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/settings/chromeAppExtConfPublic

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.application.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-conf-chromeapp.read

Request

Custom Headers

  • The preferred language to use for error messages

    Default: en-US

Path Parameters

  • Unique ID of the application using the push service

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/settings/chromeAppExtConfPublic' 
      --header 'accept: application/json' 
    

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
  • {
      "senderId": "string"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'Push GCM Configuration' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

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

Device registrations for the push service are retrieved for the specified criteria. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/devices

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.device.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-device.list

Request

Custom Headers

  • The Authorization Token associated with the 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.

    Possible values: collection format: multi

  • Retrieves device registrations only for the specified user.

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/devices?expand=true'   --header 'accept: application/json' 

Response

Status Code

  • Successfully retrieved the devices

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

  • The 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
  • {
      "code": "FPWSE0005E",
      "message": " Invalid value was provided. Check the 'offset' parameter value."
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

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. Available in client side frameworks.

POST /apps/{applicationId}/devices

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.device.create

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-device.create

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

Examples:
View
  • curl --request POST   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/devices?expand=true' 
      --header 'accept: application/json' 
      --header 'clientSecret: <CLIENT_SECRET>' 
      --data '{"deviceId":<YOUR_DEVICE_ID>,"platform":"A","token":<PUSH_TOKEN>}' 
    

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
  • {
      "createdMode": "API",
      "createdTime": "2015-08-23T09:21:02Z",
      "deviceId": "TestDeviceId",
      "userId": "TestUserId",
      "lastUpdatedTime": "2015-08-23T09:21:02Z",
      "platform": "A",
      "token": "************",
      "vapidRegistration": false
    }
  • {
      "code": "FPWSE0001E",
      "message": "Not Found - Targeted resource 'PushApplication' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0002E",
      "message": "Conflict - Targeted resource 'PushDevice' already exists. Check the 'TestDeviceId' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Retrieves report of devices registered

Device registrations report for the push service are retrieved for the specified criteria. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/devices/report

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.device.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-device.report.read

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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
  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/devices/report' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "android": 1000,
      "ios": 3500,
      "chrome": 200,
      "firefox": 500,
      "safari": 10,
      "chromeAppExt": 30,
      "all": 5240
    }
  • {
      "code": "FPWSE0005E",
      "message": "Invalid value was provided. Check the 'days' parameter value."
    }

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. Available in client side frameworks.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.device.delete

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-device.delete

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

  • curl --request DELETE   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/devices/<YOUR_DEVICE_ID>' 
      --header 'accept: application/json' 
      --header 'clientSecret: <CLIENT_SECRET>' 
    

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
  • {
      "code": "FPWSE0001E",
      "message": "Not Found - Targeted resource 'PushApplication' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Retrieves an existing device registration of push

Device registrations for a push service that are retrieved for a specific deviceId. This API is not available as a part of any frameworks. Use REST to utilise the feature.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.device.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-device.read

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

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/devices/<YOUR_DEVICE_ID>' 
      --header 'accept: application/json' 
      --header 'clientSecret: <CLIENT_SECRET>' 
    

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
  • {
      "createdMode": "API",
      "createdTime": "2015-08-23T09:21:02Z",
      "deviceId": "TestDeviceId",
      "userId": "TestUserId",
      "lastUpdatedTime": "2015-08-23T09:21:02Z",
      "platform": "A",
      "token": "************",
      "vapidRegistration": false
    }
  • {
      "code": "FPWSE0001E",
      "message": "Not Found - Targeted resource 'PushApplication' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

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. Client SDKs internally do this when the register request is called.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.device.update

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-device.update

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

Examples:
View
  • curl --request PUT   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/devices/<YOUR_DEVICE_ID>' 
      --header 'accept: application/json' 
      --header 'clientSecret: <CLIENT_SECRET>' 
      --data '{"deviceId":<YOUR_DEVICE_ID>,"platform":"A","token":<PUSH_TOKEN>}' 
    

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
  • {
      "createdMode": "API",
      "createdTime": "2015-08-23T09:21:02Z",
      "deviceId": "TestDeviceId",
      "userId": "TestUserId",
      "lastUpdatedTime": "2015-08-23T09:21:02Z",
      "platform": "A",
      "token": "************",
      "vapidRegistration": false
    }
  • {
      "code": "FPWSE0001E",
      "message": "Not Found - Targeted resource 'PushApplication' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get tags

Retrieves all or a subset of tags in the application. Available in client side frameworks.

GET /apps/{applicationId}/tags

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.tags.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-tag.list

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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

    Possible values: collection format: multi

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/tags' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

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. This API is not available as a part of any frameworks. Use REST to utilise the feature.

POST /apps/{applicationId}/tags

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.tags.create

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-tag.create

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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

Examples:
View
  • curl --request POST   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/tags' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
      --data '{"name": "SampleTag","description": "Description about SampleTag"}' 
    

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
  • {
      "createdMode": "API",
      "createdTime": "2015-08-22T18:19:58Z",
      "description": "Description about SampleTag",
      "href": "BASEURL/imfpush/v1/apps/APPID/tags/Test",
      "lastUpdatedTime": "2015-08-22T18:19:58Z",
      "name": "SampleTag"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0002E",
      "message": "Conflict - Targeted resource 'PushTag' already exists. Check the 'SampleTag' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Delete tag

Delete the tag in the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.tags.delete

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-tag.delete

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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

  • curl --request DELETE   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/tags/<TAG_NAME>' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'PushTag' does not exist. Check the 'Sample' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Retrieve detailed tag information

Retrieves specified tag in the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.tags.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-tag.read

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/tags/<TAG_NAME>' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

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
  • {
      "description": "Description about SampleTag",
      "name": "SampleTag"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'PushTag' does not exist. Check the 'Sample' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Updates tag information

Updates the tag referenced by the tagName of the application referenced by the applicationId. This API is not available as a part of any frameworks. Use REST to utilise the feature.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.tags.update

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-tag.update

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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

Examples:
View
  • curl --request PUT   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/tags/<TAG_NAME>' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
      --data '{"name": "SampleTag","description": "Description about SampleTag"}' 
    

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
  • {
      "createdMode": "API",
      "createdTime": "2015-08-22T18:19:58Z",
      "description": "Description about SampleTag",
      "href": "BASEURL/imfpush/v1/apps/APPID/tags/Test",
      "lastUpdatedTime": "2015-08-22T18:19:58Z",
      "name": "SampleTag"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'PushTag' does not exist. Check the 'Sample' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

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. Available in client side frameworks.

DELETE /apps/{applicationId}/subscriptions

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.subscriptions.delete

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-subscription.delete

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

  • curl --request DELETE   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/subscriptions?tagName=<TAG_NAME>&deviceId=<DEVICE_ID>' 
      --header 'accept: application/json' 
      --header 'clientSecret: <CLIENT_SECRET>' 
    

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
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'PushTag' does not exist. Check the 'Sample' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Retrieves all or a subset of existing subscriptions

Retrieves subscriptions for the push service for the specified criteria. Available in client side frameworks.

GET /apps/{applicationId}/subscriptions

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.subscriptions.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-subscription.list

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

    Possible values: collection format: multi

  • curl --request GET   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/subscriptions' 
      --header 'accept: application/json' 
      --header 'clientSecret: <CLIENT_SECRET>' 
    

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
  • {
      "code": "FPWSE0001E",
      "message": "Not Found - Targeted resource 'PushApplication' does not exist. Check the 'UnknownApplication' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

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. Available in client side frameworks.

POST /apps/{applicationId}/subscriptions

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.subscriptions.create

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-subscription.create

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

Examples:
View
  • curl --request POST   --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/subscriptions' 
      --header 'accept: application/json' 
      --header 'clientSecret: <CLIENT_SECRET>' 
      --data '{"deviceId": <DEVICE_ID>,"tagName": <TAG_NAME>}' 
    

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
  • {
      "deviceId": "TestDeviceId",
      "id": "1234",
      "tagName": "SampleTag"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'PushDevice' does not exist. Check the 'TestDeviceId' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get channels

Retrieves all or a subset of channels in the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/channels

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.channels.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-channel.list

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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 channel 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

  • curl --request GET 
      --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/channels' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

Response

Status Code

  • Successfully retrieved channels.

  • The request was not understood by the push server.

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

  • 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
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Create a channel

Creates a channel with the unique ID in the application, which is referenced by the applicationId parameter. The channel has associated with a name of the channel. The channel ID cannot be updated after it is created. This API is not available as a part of any frameworks. Use REST to utilise the feature.

POST /apps/{applicationId}/channels

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.channels.create

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-channel.create

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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

The channel properties

Examples:
View
  • curl --request POST 
      --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/channels' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
      --data '{    "channelId": "channel1",    "channelName": "SampleChannel",    "channelProperties": {      "importance": 3,      "enableLights": true,      "enableVibration": true,      "lightColor": "green",      "lockScreenVisibility": 1,      "groupId": "group1",      "bypassDND": true,      "description": "channel description 1",      "showBadge": true,      "sound": "name",      "vibrationPattern": [        0,        1000,        500,        1000      ]    }  }' 
    

Response

Status Code

  • Successfully created channel.

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

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

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

  • A channel 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
  • {
      "channelId": "channel1",
      "channelName": "SampleChannel",
      "channelProperties": {
        "importance": 3,
        "enableLights": true,
        "enableVibration": true,
        "lightColor": "green",
        "lockScreenVisibility": 1,
        "groupId": "group1",
        "bypassDND": true,
        "description": "channel description 1",
        "showBadge": true,
        "sound": "name",
        "vibrationPattern": [
          0,
          1000,
          500,
          1000
        ]
      }
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0002E",
      "message": "Conflict - Targeted resource 'PushChannel' already exists. Check the 'channel1' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Delete channel

Deletes the channel in the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

DELETE /apps/{applicationId}/channels/{channelId}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.channels.delete

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-channel.delete

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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 channel for the push service

  • curl --request DELETE 
      --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/channels/<CHANNEL_ID>' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

Response

Status Code

  • Successfully deleted the channel.

  • 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.

  • Application or the channel was not found.

  • An internal server error has occurred.

Example responses
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'PushChannel' does not exist. Check the 'channel1' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Retrieve detailed channel information

Retrieves specified channel in the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/channels/{channelId}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.channels.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-channel.read

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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 channel in application

  • curl --request GET 
      --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/channels/<CHANNEL_ID>' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

Response

Status Code

  • Successfully retrieved channel details.

  • The request was not understood by the push server.

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

  • Application or the channel 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
  • {
      "channelId": "channel1",
      "channelName": "SampleChannel",
      "channelProperties": {
        "importance": 3,
        "enableLights": true,
        "enableVibration": true,
        "lightColor": "green",
        "lockScreenVisibility": 1,
        "groupId": "group1",
        "bypassDND": true,
        "description": "channel description 1",
        "showBadge": true,
        "sound": "name",
        "vibrationPattern": [
          0,
          1000,
          500,
          1000
        ]
      }
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'PushChannel' does not exist. Check the 'channel1' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Updates channel name

Updates the channel referenced by the channelId of the application referenced by the applicationId. This API is not available as a part of any frameworks. Use REST to utilise the feature.

PUT /apps/{applicationId}/channels/{channelId}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.channels.update

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-channel.update

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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 channel

The channel properties

Examples:
View
  • curl --request PUT 
      --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/channels/<CHANNEL_ID>' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
      --data '{    "channelId": "channel1",    "channelName": "SampleChannel",    "channelProperties": {      "importance": 3,      "enableLights": true,      "enableVibration": true,      "lightColor": "green",      "lockScreenVisibility": 1,      "groupId": "group1",      "bypassDND": true,      "description": "channel description 1",      "showBadge": true,      "sound": "name",      "vibrationPattern": [        0,        1000,        500,        1000      ]    }  }' 
    

Response

Status Code

  • Successfully updated the channel.

  • 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 channel 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
  • {
      "channelId": "channel1",
      "channelName": "SampleChannel",
      "channelProperties": {
        "importance": 3,
        "enableLights": true,
        "enableVibration": true,
        "lightColor": "green",
        "lockScreenVisibility": 1,
        "groupId": "group1",
        "bypassDND": true,
        "description": "channel description 1",
        "showBadge": true,
        "sound": "name",
        "vibrationPattern": [
          0,
          1000,
          500,
          1000
        ]
      }
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'PushChannel' does not exist. Check the 'channel1' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Get channel groups

Retrieves all or a subset of channel groups in the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/channels/channelGroups

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.channelgroups.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-channel-group.list

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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 channel group 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

  • curl --request GET 
      --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/channelGroups' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

Response

Status Code

  • Successfully retrieved channels.

  • The request was not understood by the push server.

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

  • 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
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Create a channel group

Creates a channel group with the unique ID in the application, which is referenced by the applicationId parameter. The channel group has associated with a name of the channel group. The channelgroup ID cannot be updated after it is created. This API is not available as a part of any frameworks. Use REST to utilise the feature.

POST /apps/{applicationId}/channels/channelGroups

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.channelgroups.create

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-channel-group.create

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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

The channel group properties

Examples:
View
  • curl --request POST 
      --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/channelGroups' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
      --data '{ "groupId": "groupId1", "groupName":"SampleGroup" }' 
    

Response

Status Code

  • Successfully created channel group.

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

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

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

  • A channel 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
  • {
      "groupId": "group1",
      "groupName": "SampleGroup",
      "createdMode": "API",
      "createdTime": "2015-08-22T18:19:58Z",
      "href": "http://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/1234/channels/channelgroups/group1",
      "lastUpdatedTime": "2015-08-22T18:19:58Z"
    }
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0002E",
      "message": "Conflict - Targeted resource 'PushChannelGroup' already exists. Check the 'group1' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Delete channel group

Deletes the channel group in the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

DELETE /apps/{applicationId}/channels/channelGroups/{groupId}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.channelgroups.delete

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-channel-group.delete

Request

Custom Headers

  • Deprecated, use Authorization instead.

  • 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 channel for the push service

  • curl --request DELETE 
      --url 'https://us-south.imfpush.cloud.ibm.com/imfpush/v1/apps/<APP_GUID>/channelGroups/<GROUP_ID>' 
      --header 'accept: application/json' 
      --header 'Authorization: Bearer <IAM_TOKEN>' 
    

Response

Status Code

  • Successfully deleted the channel group.

  • 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.

  • Application or the channel group was not found.

  • An internal server error has occurred.

Example responses
  • {
      "code": "FPWSE0004E",
      "message": "Bad Request - Invalid JSON"
    }
  • {
      "code": "FPWSE0001E",
      "message": " Not Found - Targeted resource 'PushChannelGroup' does not exist. Check the 'group1' parameter"
    }
  • {
      "code": "FPWSE0010E",
      "message": "Internal server error."
    }

Retrieve detailed channel group information

Retrieves specified channel group in the application. This API is not available as a part of any frameworks. Use REST to utilise the feature.

GET /apps/{applicationId}/channels/channelGroups/{groupId}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > name > Access policies.

  • imfpush.channelgroups.list

Auditing

Calling this method generates the following auditing event.

  • imfpush.app-channel-group.read