Cloud Messaging

API Endpoint

Run in Postman

Cloud messaging

Used for sending push notification messages to a user when something happens on their account.

For example, you may want to notify a merchant that you have received and processed their deposit by sending a message to their smartphone or browser.

On the backend we use Firebase Cloud Messaging (FCM) to manage messaging on Android, iOS and web browsers.

To send messages:

  1. Install the FCM libraries in the app.

  2. At app start-up get the FCM registration ID (sometimes called the token)

  3. The app then calls the Nomanini cloud messaging API /registrations end-point sending the registration ID. This maps the registration ID of the app to the correct merchant account ID.

  4. To send a message to the merchant, use the /messages end-point to send a message to all the apps that the merchant has logged in to.

Registrations

Registrations

POST /cloud-messaging/accounts/04294c91ae55f3256ba2c274753e8588/registrations
Requestsexample 1
Headers
Content-Type: application/json
X-Nomanini-Organisation: nomanini
Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
Body
{
  "registration_id": "a3be65509b794f8fb476ec6ed72a9309"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "registration_id": {
      "type": "string",
      "description": "The registration ID from Firebase Cloud Messaging library."
    }
  },
  "additionalProperties": false,
  "required": [
    "registration_id"
  ]
}
Responses201
This response has no content.

Registrations
POST/cloud-messaging/accounts/{account_id}/registrations

Before you can send a message to an account you need to get the registration ID from the apps installed Firebase libraries.

For info on how to get the registration ID on Android, see https://firebase.google.com/docs/cloud-messaging/android/client

Once you have the registration ID, send it to this endpoint. This associates the auth account ID with the registration ID’s.

Permissions: self, messaging:admin

URI Parameters
HideShow
account_id
string (required) Example: 04294c91ae55f3256ba2c274753e8588

The auth account ID that wants to receive push notifications.

Messages

Messages

POST /cloud-messaging/accounts/04294c91ae55f3256ba2c274753e8588/messages
Requestsexample 1
Headers
Content-Type: application/json
X-Nomanini-Organisation: nomanini
Authorization: Bearer 6518bce32048dfd1b9c205b9bb635b14
Body
{
  "title": "Deposit received",
  "body": "Deposit of R 100.00 has been credited to your account.",
  "data": {
    "key1": "value1"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Title of the message."
    },
    "body": {
      "type": "string",
      "description": "Body of the message."
    },
    "data": {
      "type": "object",
      "description": "An object containing arbitrary key/value pairs that will be passed to the application that receives the push notification."
    }
  },
  "additionalProperties": false,
  "anyOf": [
    {
      "required": [
        "title",
        "body"
      ]
    },
    {
      "required": [
        "data"
      ]
    }
  ]
}
Responses201404
This response has no content.
This response has no content.

Messages
POST/cloud-messaging/accounts/{account_id}/messages

Send push notifications to all the applications that previously registered to this account.

If you receive a 201 Created then the message was accepted by the gateway and will be sent to the applications.

If the account does not have any registration tokens associated with it you will receive an http 404 Not Found error.

The data object will accept arbitrary key/value pairs, but there are some notable keys which can be sent:

  • account_id - The app will use this to decide if the user has to sign in when tapping the notification.

  • type - The type of notification. Can drive navigation behavior.

Permissions: messaging:admin

URI Parameters
HideShow
account_id
string (required) Example: 04294c91ae55f3256ba2c274753e8588

The auth account ID that wants to receive push notifications.

Generated by aglio on 18 Mar 2019