Sending custom Push Notifications to the Moodle App

There are two ways to send custom Push Notifications to the Moodle app users:

1. By using Moodle’s Message API implementing a message provider
2. By directly using the Airnotifier (Moodle’s Push Notification server) APIs

Main differences are:

By using Moodle’s Message API, users (students, teachers, etc..) can opt-out to not receive custom notifications, they can also opt-in to receive them not only on the app but also via email. Messages sent using this API can arrive to non app users.

Using the Airnotifier API will force the user to receive the notification unless they change their app settings to not receive any notification. Messages sent using this API will only arrive to active app users.

Moodle’s Message API

Please read the official Moodle documentation, Message API, where it is explained how to create a new message provider within a plugin.

Apart from what it is explained in the Message API please notice that it is possible to add a customdata field (json-encoded) with additional parameters. Those parameters are the ones described in the Airnotifier API section bellow.

Airnotifier API

Airnotifier is the name of the Push Notification server used by Moodle. It is possible to use its own API to send custom notifications from Moodle without having to use Moodle's Message API.

Payload format

Mandatory fields:

• processor (string): Always set to moodle
• notification (number): Whether it’s a notification (1) or a message (0).
• subject (string): Notification title.
• smallmessage (string): Notification body, short text.
• fullmessage (string): Notification body, ignored if smallmessage is set.

Optional

• site (string): Site ID (md5 hash of site URL + username)
• Siteurl (string): Site URL (used to identify the site the notification is coming from)
• wwwroot (string): Moodle’s $CFG->wwwroot
• component (string): Moodle’s component that generated the notification
• contexturl (string): URL the notification is related to
• customdata (json encoded object, all fields are optional)
  • notificationiconurl (string): Icon to display in the notification (Android only).
  • notificationpictureurl (string). Large picture to display in the notification (Android only).
  • tokenpluginfile (string): Token to view the icon if needed.
  • extendedtext (string). An extended text (HTML), opened in popup when clicked.
  • appurl (string): When notification is clicked, open this URL. Has preference over contexturl but it will be ignored if extendedtext is set.
  • appurlopenin (string): Where to open the previous URL ‘browser’, ‘inapp’ or any other value.

Sample CURL requests

AIRNOTIFIER_URL: Can be obtained from Site administration > Messaging > Mobile

APP_ID: commoodlemoodlemobile for the standard Moodle app

AIRNOTIFIER_ACCESS_KEY: Your Airnotifier Access key that can be obtained from Site administration > Messaging > Mobile

DEVICE_TOKEN: The user’s receiving the notification device token, for testing purposes you can get it via the app -> App settings -> About .> Click at app version -> Push notification ID

In Moodle the push ids are in the user_devices table (pushid field), the previous table has to be joined with message_airnotifier_devices to obtain active devices.

Device could be android-fcm or ios-fcm

Simple notification, only subject and body

curl https://AIRNOTIFIER_URL/api/v2/push -X POST -H "X-AN-APP-NAME: APP_ID" -H "X-AN-APP-KEY: AIRNOTIFIER_ACCESS_KEY" --data '{"device": "android-fcm", "token": "DEVICE_TOKEN",  "extra": {"processor" : "moodle", "notification": 1, "subject": "Title test", "fullmessage": "Message test"}}'</syntaxhighlight>

Notification opening a popup with custom content on the app

curl https://AIRNOTIFIER_URL/api/v2/push -X POST -H "X-AN-APP-NAME: APP_ID" -H "X-AN-APP-KEY: AIRNOTIFIER_ACCESS_KEY" --data '{"device": "android-fcm", "token": "DEVICE_TOKEN", "extra": {"processor" : "moodle", "notification": 1, "subject": "Title test", "fullmessage": "Message test", "customdata": "{\"extendedtext\" : \"Extended tex that will open on a popupt\", \"notificationiconurl\" : \"https://picsum.photos/50\", \"notificationpictureurl\" : \"https://picsum.photos/200\"}"}}'

Notification opening URL that can be handled by the app (a course within the app)

curl https://AIRNOTIFIER_URL/api/v2/push -X POST -H "X-AN-APP-NAME: APP_ID" -H "X-AN-APP-KEY: AIRNOTIFIER_ACCESS_KEY" --data '{"device": "android-fcm", "token": "DEVICE_TOKEN", "extra": {"processor" : "moodle", "notification": 1, "subject": "Title test", "fullmessage": "Message test", "customdata": "{ \"appurl\" : \"https://mymoodlesite.net/course/view.php?id=18\", \"notificationiconurl\" : \"https://picsum.photos/50\", \"notificationpictureurl\" : \"https://picsum.photos/200\"}"}}'