Push

The mobile push channel in the Business Messaging API is a solution for Android or iOS developers that want to send push notifications to their apps using phone numbers instead of the standard Firebase or APNS tokens or credentials. Devices without a SIM card (e.g. tablet, iPad) are also supported by using installation identifiers instead of phone numbers.

The push client consists of a library that needs to be included in your iOS and/or Android project. The library allows for receiving incoming push messages and optionally for registering an end-users phone number via an OTP.

There is a version 1 and version 2 of the push client SDK. Version 2 of the SDK supports rich features, the fact sheet below is based on V2.

When sending messages via mobile push using the Business Messaging API, the CM platform will look up the corresponding push token for the given phone number or installation identifier. If a push token is present, the push message will be send out. Our client libraries will allow you to receive them. Sending push messages by phone number also allows for a fallback to SMS.

Fact sheet

The fact sheet below assumes you are using the SDK V2. V1 only supports simple text and data delivery.

🚧

Note*

Only supported by making use of CMPush V2 SDK, not supported via SMS fallback.

Onboarding

The user base for the push channel consist of iOS and Android developers. Using the available libraries they can build an app that supports receiving push messages sent via the Business Messaging API to a phone number, with a fallback to SMS if needed.

We need credentials from the Google's FCM and/or Apple's APNs development environments to allow us to push messages to the app that's being developed.

Onboarding is available as early access via our Channels portal. In the portal, you will be presented with an onboarding page in which you have to provide CM.com information about your mobile app such as credentials from the Google's FCM and/or Apple's APNs development environments.

Integrating the libraries into your app

Android

To enable pushing messages to an Android app you need to add Firebase to your app and you have to add the CMPush Android library to your project.

The library itself and a detailed explanation of how to add it to your Android Project is available on the official GitHub repo for the Android library

iOS

To enable pushing messages to your iOS app you need to enable push in your app settings and you have to add the CMPush framework to your project.
The framework and a detailed explanation of how to add it to your iOS Project is available on the official GitHub repo for the iOS library.

Business rules

In other channels, like Twitter or WhatApp, the client applications are produced by 3rd parties. In the case of push, you write your own client. Therefore, there are no 3rd party guidelines or regulations regarding messages. However, we do adhere to the general rules for sending messages using the CM platform found here:
https://www.cm.com/en-gb/app/legal/cm-com/terms-and-conditions/

Considerations

The costs of the OTP calls will be debited on your account at CM.

To prevent abuse, OTP calls are throttled at:

• 3 attempts per phone number per 5 minutes
• 3 attempts per installation id per 5 minutes
• 6 attempts per IP address per 5 minutes

Limitations of CMPush V1

When making use of the CMPush V1 SDK, the following limitations are applicable:

• Mobile Push works in a single direction, from the Business Messaging API to the end-user's phone (MT, or mobile-terminated). As the end-user has no way to respond to push messages, there is no MO (mobile-originated) traffic.

  An exception are status reports (SRs). These are sent when a message is received by the app on the end user's phone and they will arrive in the status report webhook.

• While we keep a list of installation identifiers, phone numbers and corresponding push credentials on our platform, this data is only available for reference via events when making use of CMPush V2 SDK. For V1, this means you should implement some functionailty in your own app that notifies you when a device is onboarded successfully, and that stores the installation identifier and phone number in a database you manage.
  You could, for example, develop a webhook somewhere that you can call to pass data of the users that installed your app.

prerequisites

Before you can implement the push channel in your iOS or Android apps, you should have a developer account and a project set up at Apple and/or Google.

Sending a message

Sending a message works in much the same way as sending an SMS message.

In the onboarding process of your mobile app, we will provide you with a unique sender id called a channel account id to use in the dedicated appkey field.

❗️

Warning

The channel account id is the identifier of your app within CM and should never be incorporated into webpages or open-source software where it can be exposed to 3rd parties.

The to field can either be

• Recipients phone number
• Recipients installation id, fallback if user hasn't configured their phone number in your app

The from field is optional where you can specify the sender for a fallback SMS.

Receiving a message / Inbound flow

Push is a one-way communications channel, but we do send status reports that indicate whether a message arrived in your client app.

To receive these status reports, you will need to configure an inbound flow. You can find more information about how to do this using our status report webhooks in the messaging gateway app.

Message examples

Below you will find an example of a simple push message.

Direct message with plain text

{
  "messages": {
    "authentication": {
      "producttoken": "Your product token"
    },
    "msg": [
      {
        "allowedChannels": ["MobilePush", "SMS"],
        "from": "Your sender",
        "to": [{
            "number": "Recipients phone number/installation identifier"
        }],
        "body": {
          "type": "auto",
          "content": "This is the content of my push message."
        },
        "appkey": "Your channel account"
      }
    ]
  }
}

Direct message with text and image

In the example below we send a simple rich content message that contains both text and an image.

Only supported if your app makes use of CMPush V2 SDK.

{
   "messages":{
      "authentication":{
         "producttoken":"Your product token"
      },
      "msg":[
         {
            "allowedChannels":[
               "MobilePush"
            ],
            "from":"Your sender",
            "to":[
               {
                  "number":"Recipients phone number/installation identifier"
               }
            ],
            "body":{
               "type":"auto",
               "content":"Fallback Text"
            },
           "appkey": "Your channel account",
            "richContent":{
               "conversation":[
                  {
                     "text":"CM.com - Be part of it.",
                     "media":{
                        "mediaName":"cm.png",
                        "mediaUri":"https://www.cm.com/cdn/cm/cm.png",
                        "mimeType":"image/png"
                     }
                  }
               ]
            }
         }
      ]
   }
}

Direct message with reply suggestion

In the example below we send a rich content message that contains a text and some reply suggestions.

Only supported if your app makes use of CMPush V2 SDK.

{
   "messages":{
      "authentication":{
         "producttoken":"Your product token"
      },
      "msg":[
         {
            "allowedChannels":[
               "MobilePush"
            ],
            "from":"Your sender",
            "to":[
               {
                  "number":"Recipients phone number/installation identifier"
               }
            ],
            "body":{
               "type":"auto",
               "content":"Fallback Text"
            },
           "appkey": "Your channel account",
            "richContent":{
               "conversation":[
                  {
                     "text":"CM.com - Be part of it.",
                     "suggestions":[
                        {
                           "action":"Reply",
                           "label":"Call me",
                           "postbackdata":"CALL"
                        },
                        {
                           "action":"Reply",
                           "label":"Email me",
                           "postbackdata":"EMAIL"
                        },
                        {
                           "action":"Reply",
                           "label":"Send me an sms",
                           "postbackdata":"SMS"
                        }
                     ]
                  }
               ]
            }
         }
      ]
   }
}

Direct message rich card content

In the example below we send a rich content message that contains elements that can be displayed as a rich card.

Only supported if your app makes use of CMPush V2 SDK.

{
   "messages":{
      "authentication":{
         "producttoken":"Your product token"
      },
      "msg":[
         {
            "allowedChannels":[
               "MobilePush"
            ],
            "from":"Your sender",
            "to":[
               {
                  "number":"Recipients phone number/installation identifier"
               }
            ],
            "body":{
               "type":"auto",
               "content":"Fallback Text"
            },
           "appkey": "Your channel account",
            "richContent":{
               "conversation":[
                  {
                     "header":"Contact options",
                     "text":"Hi, what can I do for you?",
                     "media":{
                        "mediaName":"cm.png",
                        "mediaUri":"https://www.cm.com/cdn/cm/cm.png",
                        "mimeType":"image/png"
                     },
                     "suggestions":[
                        {
                           "action":"Reply",
                           "label":"Call me",
                           "postbackdata":"call-me"
                        },
                        {
                           "action":"Reply",
                           "label":"Email me",
                           "postbackdata":"email-me"
                        },
                        {
                           "action":"Reply",
                           "label":"Send me an sms",
                           "postbackdata":"send-me-sms"
                        }
                     ]
                  }
               ]
            }
         }
      ]
   }
}