Push

Channel Identifier

In the API this channel can be referenced using: nativePush

This identifier can be used in the rules array, and customBody sections.

Channel Setup

To setup the Push channel please ensure you have completed these steps:

  1. You integrate the App Messaging Foundation SDK into your mobile apps in order to register the required push token details and profile id to send messages to the app(s)
  2. Configure your native push channels and authentication scheme in the App Messaging channel setup as described here. You will need to configure FCM for Android and APNS for iOS.

Sending messages

Sending native push messages is simple using the Comapi Enterprise Communications API; simply ensure that when you want to send a message using the Enterprise Communications API in your rules or ruleSet you include the nativePush channel, and follow the guidance below for creating the rest of the request:

Addressing your messages

When you integrate the App Messaging Foundation SDK into your mobile app you will need to provide a callback for the SDK to authorise and identify app users. The callback should issue a JWT using the settings you specified, and importantly include the id or the user (by default in the sub claim) which will be used as the profile id for the user. You should ensure you start a session with the SDK which will call the auth callback in your app and the App Messaging Foundation SDK will now acquire the native push tokens automatically from the device and upload them against the profile your JWT claims to represent.

Now to target who a App Messaging message is delivered to simply include the profileId for the user in the to section of the request. This will send a push message to mobile devices associated with the profile id.

Integrating the App Messaging Foundation SDK into your AppIntegrating the App Messaging Foundation SDK into your App

Integrating the App Messaging Foundation SDK into your App

Message content

You will need to specify a body and title for your push messages. The body is the main body text of your message and we recommend keeping this to 160 characters to ensure it can be displayed in full on most mobile devices. The title will be shown above the body text on Android and concatenated to the front of the body text on iOS, and is used to give context to the message.

Examples:

{
  "body": "A push message sent from the One API",
  "title": "dotdigital news!",
  "to": {
    "profileId": "[email protected]"
  },
  "rules": [
    "nativePush"
  ]
}

📘

Badge Counts / Custom Behaviours

Please use a customBody to define advanced / device specific features such as iOS badge counts or custom data payloads to drive deep links etc...

Channel Options

The nativePush channel has no channel options.

Custom Body

The Comapi Enterprise Communications API automatically creates basic psuh messages for you if you define the body and title properties when sending a message, but you can specify advanced options if you use the customBody property and define a nativePush object within it using the details below:

Property

Type

Description

alert*

messageAlert object

The specifics of the push message alert

messageAlert object

Property

Type

Description

title

string

Title for the notification to send to all platforms. Note that this is ignored if any details are set in platforms

body

string

Body for the notification to send to all platforms. Note that this is ignored if any details are set in platforms

platforms

messageAlertPlatforms object

The platform specific details for the alert. If specified, these are set verbatim and alert.title / alert.body values are ignored

messageAlertPlatforms

Property

Type

Description

apns

messageAlertApns object

The APNS native channel push message specific details

fcm

messageAlertFcm object

The FCM native channel push message specific details

messageAlertApns

Property

Type

Description

badge

integer

The value to display on the application badge

sound

string

The soundfile to play on the device when the notification arrived

alert*

string

The alert to display on the device when the notification arrives

payload

object

The data payload to send to the device

messageAlertFcm

Property

Type

Description

collapse_key

object

The collapse key to send to FCM

data

object

The payload to send to the device

notification*

messageAlertFcmNotification object

Details of the notification to display

messageAlertFcmNotification

Property

Type

Description

title*

string

The title to display

body*

string

The body to display

icon

string

The icon to display

Examples of sends using custom bodies are:

{
  "to": {
    "profileId": "[email protected]"
  },
  "customBody": {
    "nativePush": {
      "alert": {
        "platforms": {
          "apns": {
            "alert": "Push message send from Comapi",
            "badge": 1
          },
          "fcm": {
            "notification": {
              "title": "Comapi news!",
              "body": "Push message send from Comapi"
            }
          }
        }
      }
    }
  },
  "rules": [
    "nativePush"
  ]
}

Receipts and Inbounds

To receive feedback Push channel sends please see the following:

If you need to to know the status of messages you've sent using one of our Enterprise Communications API, you can request that delivery receipts are forwarded to a URL of your choosing using Comapi's webhook system. See the events in the Message Events section for more details on the receipt events you can receive.

You can receive the following types of receipts, as the Push channel in a fire and forget style communication:

  • Sent
  • Failed - If a push cannot be sent to any of the profiles devices

👍

Check out our quick starts...

Check out our quick starts for simple code examples of how to send with the "One" API