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
  • Request format
  • Response format
• Add or remove registration IDs from a group
  • Request format
  • Response format
• Retrieve a list of registration IDs from a group
  • Request format
  • Response format
• Send downstream messages to group
  • Request format
  • Response format

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