Group Based Messaging
Group Messaging allows you to send messages to a group of devices in a single API call where group membership is managed by your app server. This way, if a user owns multiple devices, they can add all their devices to a single group and send messages to that group, and therefore to all their devices.
- Create a group
- Add or remove registration IDs from a group
- Retrieve a list of registration IDs from a group
- Send downstream messages to group
Before sending messages to a group, you must obtain Registration IDs for each device you want to add to the group.
Create a group
To create a group, send a POST request to the group name with a list of registration IDs that will be part of that group. ADM returns the count of those registration IDs which were successful, as well as a list of any failed registration IDs.
Request format
POST /v1/messaging/group/operations
Host: api.amazon.com
Authorization: Bearer (ACCESS_TOKEN)
Content-Type: application/json
{
"operation": "create",
"group_name": "app_group_name",
"registration_ids": ["regId1","regId2","regId3"]
}
The POST URL is made up of the second line (Host) and the first line (POST). When you add those together, you get the full URL, like this:
https://api.amazon.com/v1/messaging/group/operations
The group_name acts as an identifier for all operations such as add, remove, or send downstream messages to the group. Be sure to save the group_name on your server, or associate it with a unique identifier on your server.
Keep these group_name requirements in mind:
- It’s made up of alphanumeric characters
- It does not include private or confidential information
Response format
A partially successful response looks like this:
{
"success":1,
"failure":2,
"failed_registration_ids":["regId1","regId2"]
}
A fully successful response looks like this:
{
"success":3,
"failure":0
}
In both cases the ADM group will be created. If the success field indicates 0, the group will not be created.
Add or remove registration IDs from a group
Use the add operation to add registration IDs to a group, and the remove operation to remove registrations IDs from a group.
Here is an example of a request to add registration IDs to a group.
Request format
POST /v1/messaging/group/operations
Host: api.amazon.com
Authorization: Bearer (ACCESS_TOKEN)
Content-Type: application/json
{
"operation": "add",
"group_name": "app_group_name",
"registration_ids": ["regId1","regId2"]
}
The POST URL is made up of the second line (Host) and the first line (POST). When you add those together, you get the full URL, like this:
https://api.amazon.com/v1/messaging/group/operations
Response format
The response below indicates that 1 registration ID was successfully added to the group, and regId1 failed to be added.
{
"success":1,
"failure":2,
"failed_registration_ids":["regId1"]
}
Retrieve a list of registration IDs from a group
To retrieve a list of registration IDs from a group, send a POST request with the operation parameter set to retrieve.
Request format
POST /v1/messaging/group/operations
Host: api.amazon.com
Authorization: Bearer (ACCESS_TOKEN)
Content-Type: application/json
{
"operation": "retrieve",
"group_name": "app_group_name"
}
The POST URL is made up of the second line (Host) and the first line (POST). When you add those together, you get the full URL, like this:
https://api.amazon.com/v1/messaging/group/operations
Response format
{
"registration_ids":["regId1","regId2",..]
}
Send downstream messages to group
Sending downstream message to a group is similar to sending messages to a topic. The difference is that for group based messaging you replace "topic":"SomeTopic" with "group_name":"group_name", and change the URL to a group messaging URL.
Request format
POST /v1/messaging/group/messages
Host: api.amazon.com
Authorization: Bearer (ACCESS_TOKEN)
Content-Type: application/json
Accept: application/json
{
"group_name": "group_name",
"data":{"key1":"value1","key2":"value2"},
"notification":{
"title":"Notification title",
"body":"Notification Body for ADM"
}
}
The POST URL is made up of the second line (Host) and the first line (POST). When you add those together, you get the full URL, like this:
https://api.amazon.com/v1/messaging/group/messages
Response format
{
"success":1,
"failure":2,
"failed_registration_ids":["regId1","regId2"]
}
Last updated: Jan 04, 2023