Send a Multicast Push Notification

To effectively send multicast push notifications, a system must be in place to manage and map device tokens to unique identifiers such as Routee IDs, Email IDs, or Phone Numbers. Initially, each device token—a unique identifier for a device assigned by the push notification service—is added to a centralized database. These tokens are then mapped to unique IDs, organizing them in a way that they can be efficiently retrieved based on user identity. When a multicast notification is to be sent, the unique ID is specified in the request body, enabling the system to fetch all corresponding device tokens from the database. This process ensures that the notification reaches all devices associated with that ID. Additionally, the request must include device-specific configurations for Web, Android, and iOS platforms, accommodating the different technical requirements and enhancing the delivery effectiveness across varied device types. This approach ensures that notifications are not only targeted and well-managed but also tailored to meet the specific display and interaction standards of each device platform, thus maximizing reach and user engagement.

To address the need for enhanced functionality in our Push Notifications service, we have identified the necessity to introduce a new endpoint. This addition aims to streamline the process of setting up and sending push notifications efficiently. The proposed solution involves the integration of a new endpoint,, into our existing Push Notifications service. This endpoint is specifically designed to cater to Routee API users, providing them a direct and efficient method to send notifications. By utilizing this endpoint, users will be able to submit their notification requests through a standardized interface, which simplifies the way notifications are managed and dispatched. This enhancement not only improves the service's usability for developers but also enhances the overall performance by providing a specific pathway for handling push notification requests, thereby optimizing the communication workflow within the Routee platform.


Method: POST


Request Headers

AuthorizationStringBearer {access_token}


curl --location '' \
--header 'Authorization: Bearer 96ccc93f-667a-41bd-a461-4b6530cea529' \
--header 'Content-Type: application/json' \
--header 'Principal: XXX' \
--header 'Originating-Client-Id: XXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
  "routeeContactId": "XXXXXXXXXX",
  "body": {
    "title": {
      "en": "This is the title of the notification"
    "text": {
      "en": "This is the message of the notification"
    "forceLocale": "en"
  "imageUrl": "",
  "android": {
    "clickAction": "OPEN_ACTIVITY_1",
    "icon": "",
    "localizedTitle": "LOCALIZATION_TITLE_KEY",
    "localizedText": "LOCALIZATION_TEXT_KEY",
    "ttl": 3600
  "web": {
    "iconUrl": "",
    "targetUrl": "https://target.url"
  "apn": {
    "localizedTitle": "LOCALIZATION_TITLE_KEY",
    "localizedText": "LOCALIZATION_TEXT_KEY",
    "ttl": 8000
  "data": {
    "key1": "value1",
    "key2": "value2",
    "key3": "value3",
    "key4": "value4"
 "callback": {
    "url": ""


200 OK
    "routeeContactId": "64be7af142fe590001a22923"

Request Params

NameMandatoryTypeNotes & Validation Checks
implementationIdYesStringThere should be an implementation with the particular id that belongs to the accountId.
Not blank.
routeeContactIdYesStringroutee contact id
bodyNoObjectThe notification's body which contains the following fields:
body.titleYesObjectThe notification's title.
Map: (Key) NotBlank - Language (ISO 639-1),
(Value) NotBlank.
body.textYesObjectThe notification's text.
Map: (Key) NotBlank - Language (ISO 639-1) ,
(Value) NotBlank.
body.forceLocaleYesStringLocalization settings. Switches body.title and body.text to the selected language.
NotNull, Language (ISO 639-1).
Title and text should contain an entry with forceLocale as their key.
imageUrlNoStringURL that should begin with https://
androidNoObjectDevice-specific parameters (Android).
android.clickActionNoStringThe action associated with a user click on the notification.
android.iconNoStringThe notification's icon.
Sets the notification icon to myicon for drawable resource myicon. If you don't send this key in the request, FCM displays the launcher icon specified in your app manifest.
android.localizedTitleNoStringThe key to the title string in the app's string resources to use to localize the title text to the user's current localization.
android.localizedTextNoStringThe key to the body string in the app's string resources to use to localize the body text to the user's current localization.
android.ttlNoNumberIn seconds
Min: 0
Max: 2.419.200
Default: Same as Firebase (current: 2.419.200)
apnNoObjectDevice-specific parameters (iOS).
apn.localizedTitleNoStringThe key for a localized title string. Specify this key instead of the title key to retrieve the title from your app's Localizable.strings files. The value must contain the name of a key in your strings file.
apn.localizedTextNoStringThe key for a localized message string. Use this key, instead of the body key, to retrieve the message text from your app's Localizable.strings file. The value must contain the name of a key in your strings file.
apn.ttlNoNumberIn seconds
Min: 0
Max: 2.419.200 :question_mark:
Default: Same as Firebase (current: 2.419.200)
webNoObjectDevice-specific parameters (web).
web.iconUrlNoStringURL that should begin with https://
web.targetUrlNoStringURL that should begin with https://
dataNoObjectThis parameter specifies the custom key-value pairs of the message's payload.
For example, with data:{"score":"3x1"}:
On Apple platforms, if the message is sent via APNs, it represents the custom data fields. If it is sent via FCM, it would be represented as key value dictionary in AppDelegate application:didReceiveRemoteNotification:.
On Android, this would result in an intent extra named score with the string value 3x1.
The key should not be a reserved word ("from", "message_type", or any word starting with "google" or "gcm").
Values should be string type.
data.keyNoStringNot Blank.
data.valueNoStringNot Blank
callbackUrlNoStringURL that should begin with https://

Extra Validations
Only one should be filled from the below fields (however they can be all null at the same time):

  • android
  • apn
  • web
  • We cannot have mismatching deviceToken type and config (example : if type is ANDROID, we must not have json “web” or “apn” – we can have either “android” or null.
  • The maps of both, title and text, should contain an entry with forceLocale as their key.

Expected Response

Here is the expected response for Web, android and IOS.

NameMandatoryTypeNotes & Validation Checks
trackingDetailsYesMapThe Map which stores information about the tracking IDs of push notifications sent to different device types.
trackingDetails.androidYesListThe List of tracking IDs of android devices.
trackingDetails.webYesListThe List of tracking IDs of web devices.
trackingDetails.iosYesListThe List of tracking IDs of iosdevices.

Example Android Response

200 OK
  "trackingDetails": {
    "android": ["6c531a0c-e921,6c531a0c-e921-4636-86b5-dd73f6e5d6c1",

Example Web Response

200 OK
  "trackingDetails": {
    "web":     ["6c531a0c-e921,6c531a0c-e921-4636-86b5-dd73f6e5d6c3"],

Example IOS Response

200 OK
  "trackingDetails": {
  "ios":    ["6c531a0c-e921,6c531a0c-e921-4636-86b5-dd73f6e5d6c4"]  

Expected Errors

Error StatusError CodeWhenError message
4000101Insufficient Balance"Insufficient balance"
400-"implementationId": empty"implementationId: must not be blank"
4040000"implementationId" : Invalid or doesn't exisit"No implementation found."
4040001"ImplementationId" without credential"Credential with type: FCM does not exist for given implementation"
400-"ttl": less than 0"apn.ttl: must be greater than or equal to 0"
400-"ttl": more than 2419200"android.ttl: must be less than or equal to 2419200"
400-"ttl": Invalid value"android.ttl: invalid value"
400-"deviceToken": "token": empty or null"deviceToken.token: must not be blank"
400-"deviceToken": "type": empty or null"deviceToken.type: invalid value"
400-"data": Value : empty"data[key1].: must not be blank"
400-"data": Empty"data: invalid value"
400-"callbackUrl" invalid"callback.url: must be a valid URL"
400-"body.title.key" Empty or null"body.title[en].: must not be blank"