Push Notification Service

Overview

This page contains useful information about Push Notification service. There are different types of push notification supported in Genesys Mobile Services:

• HttpCallback Notification
• Firebase Cloud Notification
• Apple Notification
• Orchestration Server Callback Notification
• Custom HTTP Notification

In addition to discussing these different types of notification, this page also describes Notification Propagation. For details about the configuration options available for various types of notification, see the push Section in the Configuration Options Reference.

HttpCallback Notification

This channel is used to push notifications as POST requests to a provided URL. The notification server expects a response status of 200 (HTTP_OK). The body is ignored. If the response status is not 200 then the notification is considered as failed (see Notification Propagation for more details).

Subscription Request

The URL to POST the message is specified by deviceId in the subscription request. When an event comes to the NotificationService and its tag matches the corresponding subscription, the POST request will be sent to the URL, specified by notificationDetails.deviceId.

Usage

The HTTP callback notification channel will send the HTTP request to the specified URL as a reaction to notification publishing. The format of callback HTTP is described above. The connection will be plain HTTP without TLS/SSL. The HTTP request will be done with the POST method (hardcoded, not configurable), where the body will be the plain string, passed as "message" in the notification (see Notification API). Sample Request body:

{"subscriberId":"A1",
 "notificationDetails":{
    "deviceId":" http://localhost:8080/gms-web/gms/httpcb_notification/value/suffix",
    "type":"httpcb"},
 "filter":"*"}

Firebase Cloud Messaging Notification

Important

FCM Http V1 is now the default method. If you face any issues, check if the FCM Http V1 configuration is correct.

HTTP V1

Introduced in: 8.5.240

The latest version of FCM API is FCM HTTPS V1. It provides more security via access tokens and the access tokens follow OAuth model and also provides more efficient customization of messages across platforms. This is the recommended API to be used.

To configure Native Push Notification through Firebase Cloud Messaging, configure the following settings:

push section

This is the default configuration section, If there is no provider configured.

Sl.No	Property Name	Property Value	Mandatory	Description
1.	pushEnabled	fcm_http_v1	Yes	This property is used to enable the push notification, multiple configurations can be separated by comma.
2.	fcm_http_v1.ServiceAccountFile.absolute-path	/<your path>/service-account.json	Yes	This is the path to the service-account.json, which is downloaded from fcm account. It is responsible for the required information of OAuth token retrival. Eg : /usr/bin/service-account.json
3.	fcm_http_v1.ServerUrl	https://fcm.googleapis.com/v1/projects/<your project id>/messages:send	Yes	This is the fcm URL, in which we need to send notification message. <your project id> should be filled with your project id from fcm console project settings. Refer to Google Firebase documentation. Eg : https://fcm.googleapis.com/v1/projects/my-sample-project-a2f5b/messages:send.

push.provider.android-fcm-http-v1 section

This section should have the same properties like above section but we can configure any number of providers, below is the explanation for how to construct a section with providers.

push - is the constant value used to represent this is push notification section.

provider - is the constant value used to identify that this section will have a provider name.

android-fcm-http-v1 - is the provide name which can be anything of user’s wish or may reasonably represent what for this section is configured.

Important

DESCRIPTION

• Above properties will be loaded in the GMS booting phase, So If there is any change it requires a restart of GMS application.
• If the above required properties are not configured, GMS will not load the corresponding module like FCM or FCM-http-v1 and every request will produced 503 response without any Exception or Error, It can only be identified in the startup logs whether all the required fields are loaded or got any Error.

[push]
pushEnabled=fcm_http_v1
fcm_http_v1.ServiceAccountFile.absolute-path=/tmp/service-account.json
fcm_http_v1.ServerUrl=https://fcm.googleapis.com/v1/projects/my-sample-project-a2f5b/messages:send

[push.provider.fcm-http-v1-sample]
fcm_http_v1.ServerUrl=https://fcm.googleapis.com/v1/projects/my-sample-project-a2f5b/messages:send
fcm_http_v1.ServiceAccountFile.absolute-path=/tmp/service-account-sample.json
pushEnabled=fcm_http_v1

For example, you can configure _provider_name={ProviderName} for a given Callback service, or in a Chat V2 scenario, you could pass this provider name in the push_notification_provider user data of the requestChat operation.

Use fcm.title and fcm.body options to extend your configuration by creating an event-level [push.provider.{ProviderName}.event] section and then, a specific service name and event:

• [push.provider.{ProviderName}.event.{ServiceName}]
• [push.provider.{ProviderName}.event.{ServiceName}.{EventName}]

The following example shows how to configure in GMS two chat services for Bank's Saving Account and use localized messages in English and Russian. This configuration sample is applicable for Chat V2 service only.

[push.provider.bankoperations]
pushEnabled=ios,fcm_http_v1
apple.keystore=/var/genesys/gms/appleKeystore.p12
apple.keystorePassword=****
fcm_http_v1.ServerUrl=https://fcm.googleapis.com/v1/projects/my-sample-project-a2f5b/messages:send
fcm_http_v1.ServiceAccountFile.absolute-path=/tmp/service-account-sample.json

[push.provider.bankoperations.event]
fcm.body="Please open app for more details
  
[push.provider.bankoperations.event.chat.savings-english.ParticipantJoined]
fcm.title="Agent has joined an waiting"
 
 
[push.provider.bankoperations.event.chat.savings-english.Message]
fcm.title="You got new message from us"
fcm.body="Please answer us soon!"
  
[push.provider.bankoperations.event.chat.savings-russian.ParticipantJoined]
fcm.title="Агент присоединился и ждет"
fcm.body="Ответьте нам поскорее"
  
[push.provider.bankoperations.event.chat.savings-russian.Message]
fcm.title="У Вас новое сообщение!"
fcm.body="Ответьте нам поскорее"

Apple Notification

Modified in 8.5.114, 8.5.228.02

Versions older than 8.5.228.02

For versions older than 8.5.228.02, Genesys Mobile Services communicates with the Apple Push Notification Service over an asynchronous binary interface, that is no longer supported.

Warning

The Apple Push Notification service (APNs) no longer supports the legacy binary protocol as of March 31, 2021. Read more.

This means that the APN service is no longer be accessible for the legacy binary protocol. Genesys Mobiles Services stopped supporting the legacy binary protocol, which is the default protocol for Apple Push notifications. For further details, read End of Genesys Support for Apple Push Notification service (APNs) – Legacy binary protocol.

Genesys recommends that you upgrade to the latest GMS version (8.5.228.02 or higher) or migrate to a supported notification type such as:

• Firebase Cloud Notification
• Custom HTTP Notification

Version 8.5.228.02 and higher

In 8.5.228.02, GMS has been updated to use the HTTP/2 Apple Push Notification service API and now supports Apple Notifications.

This interface is a high-speed, high-capacity interface for providers; it uses a streaming TCP socket design in conjunction with binary content. The binary interface of the production environment is available through gateway.push.apple.com, port 2195; the binary interface of the sandbox (development) environment is available through gateway.sandbox.push.apple.com, port 2195. You may establish multiple, parallel connections to the same gateway or to multiple gateway instances. See more details here: Apple Push Notification Service.

Digital Channels Chat V2 API with CometD supports native push notifications through Apple Push Notification Service. To establish a TLS session with APNs, install an Entrust Secure CA root certificate on the provider’s server. If the server is running macOS, this root certificate is already part of the keychain. On other systems, the certificate might not be available. You can download this certificate from the Entrust SSL Certificates website.

For further configuration details, refer to Mandatory iOS Device Settings.

APNS Certificate

Starting in release 8.5.206.04, GMS cannot retrieve the APNS certificate generated for the APNS Sandbox Server. To generate a valid certificate, do not use the private key p12 file generated by the APNS Console. Instead, generate a new p12 file from your private key (mykey.p12) and the certificate downloaded from the Apple Console (developer_identity.cer) by executing the following OpenSSL command:

openssl x509 -in developer_identity.cer -inform DER -out developer_identity.pem -outform PEM openssl pkcs12 -nocerts -in mykey.p12 -out mykey.pem openssl pkcs12 -export -inkey mykey.pem -in developer_identity.pem -out iphone_dev.p12

Then, you can use the generated iphone_dev.p12 certificate to communicate with the Apple Sandbox Server.

Client Application Implementation

Incoming notifications are the string representation of a JSON object. To receive the message itself, please extract the node with key=message.

CometD Notification

This channel is used to push notifications on the CometD channel. When using CometD to get notifications, the CometD connection should be set up with a subscription for /_genesys.

You also need to make sure that the 'gms_user' header in all CometD related requests is set to the value uniquely representing the application end-user. Typically, this value would be set up (or at least verified) by the security gateway located between the client application and GMS.

CometD handshake request

POST http://localhost:8080/genesys/cometd
Accept-Encoding: gzip,deflate
Content-Type: application/json;charset=UTF-8
gms_user: BuzzBrain
{"version":"1.0","minimumVersion":"0.9",
"channel":"/meta/handshake","id":"0"}

HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:30:10 GMT
Content-Type: application/json 
Content-Length: 230
[{"id":"0","minimumVersion":"1.0",
"supportedConnectionTypes":["websocket","callback-polling","long-polling"],
 "successful":true,"channel":"/meta/handshake","ext": "ack":true},
"clientId":"44xkkazwfabw73jrvjsvoy4ul",
 "version":"1.0"}]

CometD /meta/connect subscription request

POST  http://localhost:8080/genesys/cometd 
Accept-Encoding: gzip,deflate 
Content-Type: application/json;charset=UTF-8
gms_user: BuzzBrain
{"channel":"/meta/connect",
"clientId":"44xkkazwfabw73jrvjsvoy4ul",
"id":"1","connectionType":"long-polling"}

HTTP/1.1 200 OK 
Date: Sun, 10 Jun 2012 08:30:10 GMT
Content-Type: application/json
 Content-Length: 116 
[{"id":"1","successful":true,
"advice":{"interval":0,"reconnect":"retry","timeout":60000},
"channel":"/meta/connect"}]

CometD /_genesys subscription request

POST  http://localhost:8080/genesys/cometd 
Accept-Encoding: gzip,deflate
Content-Type: application/json;charset=UTF-8
gms_user: BuzzBrain
[{"channel":"/meta/subscribe","subscription":"/_genesys",
"clientId":"44xkkazwfabw73jrvjsvoy4ul","id":"2"}]

HTTP/1.1 200 OK 
Date: Sun, 10 Jun 2012 08:30:10 GMT 
Content-Type: application/json
Content-Length: 85 
[{"id":"2","subscription":"/_genesys","
successful":true,"channel":"/meta/subscribe"}]

CometD long polling request

POST  http://localhost:8080/genesys/cometd 
Accept-Encoding: gzip,deflate 
Content-Type: application/json;charset=UTF-8
gms_user: BuzzBrain
{"clientId":"44xkkazwfabw73jrvjsvoy4ul",
"id":"3","channel":"/meta/connect",
"connectionType":"long-polling"}

HTTP/1.1 200 OK
Date: Sun, 10 Jun 2012 08:30:10 GMT 
Content-Type: application/json 
Content-Length: 85
[{"id":"4","successful":true,"channel":"/meta/connect"}]

Localization of push messages

GMS supports localized messages. To allow this feature, your device must supply a language at subscription time, corresponding to the application language. For example, the language can be:

Country	Language
English (United States)	en_US
English	en
Estonian	et
French	fr
...	...

Localization file format is described here.

{"subscriberId":"A1",
 "notificationDetails":{
    "deviceId":" http://localhost:8080/gms-web/gms/httpcb_notification/value/suffix",
    "type":"httpcb"},
 "language":"de",
 "filter":"*"}

See more details on configuring the push section.

Orchestration Server Callback Notification

Subscription

When subscribing to Orchestration Server callback, the user provides the Orchestration Server sessionId. This parameter is specified by notificationDetails.deviceId, with the type to be used specified as orscb.

Notification Propagation

The notification event contains 2 parameters: tag and message. The tag parameter is used for matching the subscription. If the subscription is for Orchestration Server callback, the following mappings have place:

• notificationDetails.deviceId - mapped to Orchestration Server sessionId
• notificationevent.tag - mapped to Orchestration Server eventName
• message - mapped to the message

Configuration

At the moment no specific configuration options exist for Orchestration Server. Callback relies on the corresponding ORS Service.

Providers

You will need to add the certificate-related configuration options in the current push configuration section to a NEW type section that defines the credentials for the set of customer-specific notification providers. The provider can be specified as part of the notification subscription request.

For each notification provider, create a section with the following name format: push.provider.providername. For example, push.provider.SalesAppl. This will allow you to define a different push notification provider (connection) for each group of notification messages that are sent to applications.

You can define a provider for a group of events that are to be sent to a specific application or to be sent as part of a given service. This ensures that a given application does not get messages that it was not intended to receive. This provider definition can be associated with a given service’s configuration definition or can be passed to the Create Service API for a given application.

If there is no provider defined for a subscription, then the default configuration options defined as part of the Push configuration section will be used.

The provider-related configuration options can be found here: Configuration Options. There will also be a set of these credential configuration options for debugging purposes. So, there will be two provider connections for a provider. The application will be able to specify which provider (production or debug) connection.

Support of OS-specific capabilities associated with the notification message

Each Push Notification System has a set of attributes that are sent to the application along with the base notification message. These attributes are usually related to the message definition itself and not to a given instance of the message being sent. So these additional OS attributes will be configured as part of the provider configuration definition. For each event, you will create a section with the following name format – push.provider.providername.event.eventname. For example, push.provider.SalesAppl.event.mobile.statuschanged. This is done so that the Notification APIs do not have to have these OS-specific attributes provided on the API calls. This can define for each notification message associated with each provider or defined at the general provider level for each event. Besides, you can provide these OS-specific attributes for various event groups. For example, you can do it at the individual event level (mobile.statuschanged) or an event sub-grouping (mobile.). These attributes are all independent of the level they are defined at so you could end up picking up values for the different attributes from different levels in the hierarchy. This is in the order in which they will be selected. (first to last):

• Use the event definition values associated with a specific provider definition
• Use the event definition values associated with a general provider definition
• Use the OS-specific attribute values associated with the push section

Also, the event definition can contain multiple different OS-specific attributes so you can have iOS and Android attributes defined under the same event definition. So the notification framework high-level logic for processing published events would be:

• Find the subscriptions that have registered to receive this event
• Get the subscriptions associated provider’s event configuration options for this event
• If available use them, otherwise, check the general event configuration options under the provider configuration section. If available use them otherwise get the general configuration options under the Push configuration section. If available use them otherwise this event message does not have OS-specific attributes to apply.
• Form the PNS specific message with the input from the Publish API and the event configuration options if available
• Send the message over the appropriate provider connection to the PNS.

Consider the example to illustrate the rules. Let's say that we have the subscription associated with provider SalesApp and with filter A2C.* (match all events starting with A2C). Consider that we have the following set of sections with OS-specific message formatting options:

• (0) push
• (1) push.provider.event
• (2) push.provider.event.internal
• (3) push.provider.event.internal.advanced
• (4) push.provider.event.A2C
• (5) push.provider.event.A2C.service
• (6) push.provider.event.A2C.service.statuschanged
• (7) push.provider.event.A2C.service.internal
• (8) push.provider.event.A2C.service.statuschanged.agentavailable
• (9) push.provider.SalesApp.event
• (10) push.provider.SalesApp.event.A2C.service.internal
• (11) push.provider.SalesApp.event.A2C.service.statuschanged

Consider that we have the incoming event with tag A2C.service.statuschanged.agentavailable. This event's tag will match the filter of our subscription associated with provider SalesApp and with filter A2C.*. So, we will go through the chain of sections in the following order (from most default to most concrete): 0->1->4->5->6->8->9->11 We'll traverse this chain replacing and overwriting the options from more default sections with the corresponding options from more concrete sections (this is equivalent to seeking for all options in more concrete sections first, and accessing more default only if not found in more concrete). The result set of options will be used for OS-specific message formatting.

Sensitive Options

You can set sensitive options in different sections of your application configuration. In the following example, the configuration structure allows to set the password for apple in a new section called apple-desc.

[push]
apple=apple-desc;
debug-apple=debug-apple-desc

[apple-desc]
password=*********
apple.keystore=xxxxxxxxxxx
[debug-apple-desc]
password=*********
apple.keystore=xxxxxxxxxxx

In case of:

• IOS (APNS): The password option is used instead of apple.keystorePassword.
• Microsoft (WNS): The password option is used instead of wns.clientSecret.

You do not need to change the name of other options. Genesys recommends that you create a new section to set the mandatory options and that you keep optional options in the push section. See the options' detail for more information.

Custom HTTP Notification

If you wish to use a third-party server to handle notifications, configure the push section to use Custom HTTP notifications.

[push]

pushEnabled = "customhttp"

defaultSubscriptionExpiration = 30

customhttp.url = <third-party server URL>

Your third-party server will receive HTTP POST requests formatted as follows:

POST / HTTP/1.1 <the_customhttp_target_host>
Content-Type: application/json
Content-Length: 69
Host: 135.39.40.24:51275
Connection: Keep-Alive

{"message":"<event_message>","deviceId":"<customer_device_id>"}

The received JSON contains the following parameters:

• message–can be a JSON string or a just a string.
• deviceId–ID of the device that the custom notification server will use to identify the mobile.

Important

It is important to provide adequate throughput of the Web Server which processes the customhttp notification. The latency (in other words, the processing time for a single HTTP POST request) must be as low as possible as GMS sends all notifications sequentially. The next request is only sent after a reply from the previous one. For example, if the latency is 5 milliseconds on average, then a single GMS node can send 200 notifications per second.