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, https://connect.routee.net/push-notifications/messages/multicast, 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.
Resource
Method: POST
URL: https://connect.routee.net/push-notifications/messages/multicast
Request Headers
Name | Type | Description |
---|---|---|
Authorization | String | Bearer {access_token} |
Content-Type* | String | application/json |
Request:
curl --location 'https://connect.routee.net/push-notifications/messages/multicast' \
--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": "https://pics.freeicons.io/uploads/ic",
"android": {
"clickAction": "OPEN_ACTIVITY_1",
"icon": "https://pics.freeicons.io/uploads/icons/png/15798659891536125452-512.png",
"localizedTitle": "LOCALIZATION_TITLE_KEY",
"localizedText": "LOCALIZATION_TEXT_KEY",
"ttl": 3600
},
"web": {
"iconUrl": "https://cdn-icons-png.flaticon.com/512/1006/1006771.png",
"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": "https://webhook.site/ccd40751-d757-440d-bcdf-549f87faec79"
}
}'
Response:
200 OK
{
"routeeContactId": "64be7af142fe590001a22923"
}
Request Params
Name | Mandatory | Type | Notes & Validation Checks |
---|---|---|---|
implementationId | Yes | String | There should be an implementation with the particular id that belongs to the accountId. Not blank. |
routeeContactId | Yes | String | routee contact id |
body | No | Object | The notification's body which contains the following fields: title; text; forceLocale. |
body.title | Yes | Object | The notification's title. Map: (Key) NotBlank - Language (ISO 639-1), (Value) NotBlank. |
body.text | Yes | Object | The notification's text. Map: (Key) NotBlank - Language (ISO 639-1) , (Value) NotBlank. |
body.forceLocale | Yes | String | Localization 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. |
imageUrl | No | String | URL that should begin with https:// |
android | No | Object | Device-specific parameters (Android). |
android.clickAction | No | String | The action associated with a user click on the notification. |
android.icon | No | String | The 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.localizedTitle | No | String | The key to the title string in the app's string resources to use to localize the title text to the user's current localization. Example: NOTIFICATION_TITLE |
android.localizedText | No | String | The key to the body string in the app's string resources to use to localize the body text to the user's current localization. Example: NOTIFICATION_MESSAGE |
android.ttl | No | Number | In seconds Min: 0 Max: 2.419.200 Default: Same as Firebase (current: 2.419.200) |
apn | No | Object | Device-specific parameters (iOS). |
apn.localizedTitle | No | String | The 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.localizedText | No | String | The 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.ttl | No | Number | In seconds Min: 0 Max: 2.419.200 :question_mark: Default: Same as Firebase (current: 2.419.200) |
web | No | Object | Device-specific parameters (web). |
web.iconUrl | No | String | URL that should begin with https:// |
web.targetUrl | No | String | URL that should begin with https:// |
data | No | Object | This 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.key | No | String | Not Blank. |
data.value | No | String | Not Blank |
callbackUrl | No | String | URL 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.
Name | Mandatory | Type | Notes & Validation Checks |
---|---|---|---|
trackingDetails | Yes | Map | The Map which stores information about the tracking IDs of push notifications sent to different device types. |
trackingDetails.android | Yes | List | The List of tracking IDs of android devices. |
trackingDetails.web | Yes | List | The List of tracking IDs of web devices. |
trackingDetails.ios | Yes | List | The List of tracking IDs of iosdevices. |
Example Android Response
200 OK
{
"trackingDetails": {
"android": ["6c531a0c-e921,6c531a0c-e921-4636-86b5-dd73f6e5d6c1",
"6c531a0c-e921,6c531a0c-e921-4636-86b5-dd73f6e5d6c2"],
}
}
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 Status | Error Code | When | Error message |
---|---|---|---|
400 | 0101 | Insufficient Balance | "Insufficient balance" |
400 | - | "implementationId": empty | "implementationId: must not be blank" |
404 | 0000 | "implementationId" : Invalid or doesn't exisit | "No implementation found." |
404 | 0001 | "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" |
Updated 5 months ago