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


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


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 Enterprise Communications API automatically creates basic push 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:

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


apnsmessageAlertApns objectThe APNS native channel push message specific details
fcmmessageAlertFcm objectThe FCM native channel push message specific details


badgeintegerThe value to display on the application badge
soundstringThe soundfile to play on the device when the notification arrived
alert*stringThe alert to display on the device when the notification arrives
payloadobjectThe data payload to send to the device


collapse_keyobjectThe collapse key to send to FCM
dataobjectThe payload to send to the device
notification*messageAlertFcmNotification objectDetails of the notification to display


title*stringThe title to display
body*stringThe body to display
iconstringThe icon to display

Examples of sends using custom bodies are:

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

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 the 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