HTTP API

If for some reason you need Swagger specs for this RESTful service, there is a swagger endpoint available via an HTTP path /swagger.json

Request

MongoosePush exposes one notification endpoint:

• POST /{version}/notification/{device_id}

{device_id} is the token issued by FCM or APNS. Send the notification as a JSON body, for example:

{
  "service": "apns",
  "alert":
    {
      "body": "notification's text body",
      "title": "notification's title"
    }
}

The available options are:

• service (required, apns or fcm) - push notifications provider to be used for this notification
• mode (optional, prod (default) or dev) - allows for selecting named pool configured in MongoosePush
• priority (optional, normal or high) - passed through to FCM; for APNS, normal maps to 5 and high to 10. FCM JMI notifications default to the selected pool's jmi_priority (high if unset); otherwise the provider chooses the default.
• time_to_live (optional, FCM specific) - maximum notification lifespan in seconds, as an integer. FCM JMI notifications default to the selected pool's jmi_ttl (30 if unset). See the FCM documentation.
• mutable_content (optional, true / false (default)) - for non-JMI APNS notifications, sets "mutable-content=1" in the APNS payload.
• topic (optional, APNS specific) - selects the application when the configured credentials allow multiple topics.
• tags (optional) - a list of tags used to choose a pool with matching tags. To see how tags work read: https://github.com/esl/sparrow#tags
• data (optional) - custom JSON sent to the target device. APNS places its keys at the payload root; FCM puts them in message.data. JMI delivery options are described below.
• alert (optional) - JSON structure that if provided will send a non-silent notification with the following fields:
  • body (required) - text body of the notification
  • title (required) - short title of the notification
  • click_action (optional) - for FCM its activity to run when notification is clicked. For APNS its category to invoke. Please refer to the Android/iOS documentation for more details about this action
  • tag (optional, FCM specific) - notifications aggregation key
  • badge (optional, APNS specific) - unread notifications count
  • sound (optional) - sound that should be play when the notification arrives. Please refer to the FCM / APNS documentation for more details.

At least one of alert and data is required. Supplying only data creates a silent notification; supplying alert creates a visible notification, optionally with custom data.

JMI call notifications

Set data.type to jmi and omit alert to send an incoming Jingle Message Initiation call notification. For FCM, a non-empty data.jmi-sid is recommended so MongoosePush can generate a collapse key.

For FCM, post to /v3/notification/{fcm_token}:

{
  "service": "fcm",
  "data": {
    "type": "jmi",
    "jmi-sid": "ca3cf894-5325-482f-a412-a6e9f832298d",
    "jmi-from": "romeo@montague.example/orchard"
  }
}

MongoosePush puts the data at the FCM message level and, when jmi-sid is a non-empty string, derives collapse_key as "jmi-" + jmi-sid. Priority and TTL come from the selected pool's jmi_priority and jmi_ttl; request-level priority and time_to_live override them.

For APNS, use the PushKit token as {device_id} and post to /v3/notification/{device_id}:

{
  "service": "apns",
  "topic": "com.example.app.voip",
  "data": {
    "type": "jmi",
    "jmi-sid": "ca3cf894-5325-482f-a412-a6e9f832298d",
    "jmi-from": "romeo@montague.example/orchard"
  }
}

The topic must end in .voip. MongoosePush sets the APNS push type to voip and expiration to 0, puts the data at the payload root, and omits aps.

Response

Description of the possible server responses

• 200 "OK" - the request was successful.
• 400 {"reason" : "invalid_request"|"no_matching_pool"} - the request was invalid.
• 410 {"reason" : "unregistered"} - the device was not registered.
• 413 {"reason" : "payload_too_large"} - the payload was too large.
• 429 {"reason" : "too_many_requests"} - there were too many requests to the server.
• 503 {"reason" : "service_internal"|"internal_config"|"unspecified"} - the internal service or configuration error occurred.
• 520 {"reason" : "unspecified"} - the unknown error occurred.
• 500 {"reason" : reason} - the server internal error occurred, specified by reason.