From the documentation:

thread-id | string | When displaying notifications, the system visually groups notifications with the same thread identifier together. For remote notifications, the value of the threadIdentifier property is set to the value of this request header.

Our push notification payloads:

{
    aps =     {
        alert =         {
            body = "Leeroy J asked you: Test Push Notification";
        };
        badge = 12;
        sound = default;
        "thread-id" = 9150;
    };
    n = "6kQ/0x6556";
    r = 9150;
}

{
    aps =     {
        alert =         {
            body = "Leeroy J re: Test Push Notification";
        };
        badge = 13;
        sound = default;
        "thread-id" = 9150;
    };
    n = "6l8/0x6582";
    p = 7197;
    r = 9150;
}

Here's what it looks like in Message Center:

I expected them to be visually different than other notifications... either that or grouped together when other notifications come in between. In our testing, neither is the case.

What am I doing wrong? Or am I misunderstanding this feature?

You don’t need:

• apns-collapse-id
• NotificationContentExtension

Never in the docs it's mentioned that way that you need them. It's just that they are related.

Solution:

For me it worked out of the box. It's just the iOS doesn't immediately render notifications into groups.

1. Send Notifications with thread-ids
2. Then Wait. Let your iPhone/iPad lock screen turn off. (Mine was locked).
3. Then send another message
4. If that doesn't work then just be patient a bit and try again.

Then all of the sudden it starts to group and work as expected!!! 🤯🤯🤯

For the stacking to happen you need a few notifications. If there is too much space, more likely on an iPad then it will need more to start stacking them. Also make sure you've correctly set your notification grouping setting to 'Automatic'

Other usage of thread-id:

Usage of thread-id has another purpose that is best explained within messaging apps. Think of iMessage.

1. You get a message from your friend.
2. You Long press the notification.
3. It will open a popup where you can chat from within the contentExtension
4. If your friend sends more messages, then your content-extension's didReceiveNotification will keep getting called. It gets called so you can update the conversation.

This method may be called multiple times while your view controller is visible. Specifically, it is called again when a new notification arrives whose threadIdentifier value matches the thread identifier of the notification already being displayed. The method is called on the main thread of your notification content app extension.

_{reference to didReceive(_:) docs}

For more on this see this answer

Summary

There are two distinct use cases for thread-id:

• Grouping notifications
• Getting continuous callbacks to your contentExtension for a single thread-id

---

What is apns-collapse-id?

Used if you've sent a notification and it somewhat needs correction/update. Example you're WashingtonPost and someone has just won the presidency.

You first send a notification with just a title of 'Albert Bori has won 2020 election!!' with a body of: This message will be updated shortly...

Then 3 minutes later, you get more information that he won the elections by winning in 40 states and losing in 10. So you update the body. Then you get more information of exact number of votes. So you update the body again. You can constantly update the message (with or without sound. It would then just get updated in the notification center).

Only if the user has already dismissed/viewed the notification then a notification with the same apns-collapse-id will alert/notify the user. It's not for grouping it's for coalescing/updating an existing notification!