Notify Chat Members of New Messages


KV sharing is in beta. Method shapes, limits, and behavior may change between releases.

Build a Group Chat shows new messages to members who have the chat open. This recipe notifies everyone else, with a push on their phone or computer.

The chat shares the room with each member with notify: true, which lets the two sides of each share notify each other. With to: { handle }, puter.notifications.notify() sends the notification to the other side of that share instead of to the user your app runs for. Your app calls it right after it sends a message. A member who's looking at the chat gets the notification in the page without a push, as When a notification is pushed describes.

Each share connects the room's creator with one member, so the creator can notify every member, and a member can notify the creator. For members to notify each other as well, see Let Members Notify Each Other.

This recipe uses the room, prefix, handle, user and sendMessage() from Build a Group Chat. Your site also needs to serve /puter-sw.js, as Reach a User When Your App Is Closed shows.

Notify Through the Shares

A member reaches the creator through their own share's handle. The creator reaches each member through that member's share, which puter.kv.listSharedByMe() lists a page at a time:

async function memberHandles () {
    const handles = [];
    let cursor;
    do {
        const page = await puter.kv.listSharedByMe({ state: 'live', limit: 200, cursor });
        for (const share of page.items) {
            if (share.prefix === prefix && share.notify) handles.push(share.handle);
        }
        cursor = page.cursor;
    } while (cursor);
    return handles;
}

async function notifyRoom (text) {
    const { roomId, title } = await room.get('meta');
    const notification = {
        title: `${user.username} in ${title}`.slice(0, 120),
        text: text.slice(0, 240),
        channel: 'chat',
        group: `room:${roomId}`,
        target: `/rooms/${roomId}`,
        data: { roomId },
    };

    const handles = handle ? [handle] : await memberHandles();
    await Promise.allSettled(handles.map((to) =>
        puter.notifications.notify({ ...notification, to: { handle: to } })));
}

const text = 'Who is bringing the tent?';
await sendMessage(text);
await notifyRoom(text);

The listing covers every room the creator shared, so the code keeps the shares of this room. It uses Promise.allSettled() so that one member who can't be notified doesn't stop the rest. A member can't be notified once their share stopped, or after they blocked the creator. notify() lists the errors.

The notification names your app, not the sender, so the title says who wrote the message. The group makes a new message replace the member's notification for the same room instead of adding another, so a busy room doesn't use up the daily notification limit.

Say What a Push Shows

On every page load, register a handler for the chat channel with puter.notifications.onPush(), and open the room when the user taps a notification with puter.notifications.on('click'):

await puter.notifications.onPush('chat', (n) => ({
    title: n.title,
    body: n.text ?? '',
    url: n.target ?? '/',
}));

puter.notifications.on('click', ({ data }) => {
    if (data?.roomId) openRoomById(data.roomId);
});

Here openRoomById() is your app's own function that shows a room.

While the chat is open, the notification reaches this handler in the page. When the tab is visible and focused, nothing is pushed. Otherwise the notification goes out as a push, and the same handler runs in your service worker to decide what it shows. The message itself arrives through the room's watch().

Turn Notifications On

Give the room a "Notify me" button. Browsers only show their permission prompt from a click, so call puter.notifications.enable() there:

document.getElementById('notify').addEventListener('click', async () => {
    const pushes = await puter.notifications.enable();
    console.log(pushes ? 'You will be notified' : 'Notifications are off');
});

puter.notifications.enable() turns pushes on in this browser only. A member who wants them on their phone too presses the button there. On iPhone and iPad, that's from your site added to the Home Screen, as Where pushes work explains. A push is billed to the member who receives it.

Full Code

The page, after the room is open:

await puter.notifications.onPush('chat', (n) => ({
    title: n.title,
    body: n.text ?? '',
    url: n.target ?? '/',
}));

puter.notifications.on('click', ({ data }) => {
    if (data?.roomId) openRoomById(data.roomId);
});

async function memberHandles () {
    const handles = [];
    let cursor;
    do {
        const page = await puter.kv.listSharedByMe({ state: 'live', limit: 200, cursor });
        for (const share of page.items) {
            if (share.prefix === prefix && share.notify) handles.push(share.handle);
        }
        cursor = page.cursor;
    } while (cursor);
    return handles;
}

async function notifyRoom (text) {
    const { roomId, title } = await room.get('meta');
    const notification = {
        title: `${user.username} in ${title}`.slice(0, 120),
        text: text.slice(0, 240),
        channel: 'chat',
        group: `room:${roomId}`,
        target: `/rooms/${roomId}`,
        data: { roomId },
    };

    const handles = handle ? [handle] : await memberHandles();
    await Promise.allSettled(handles.map((to) =>
        puter.notifications.notify({ ...notification, to: { handle: to } })));
}

async function sendAndNotify (text) {
    await sendMessage(text);
    await notifyRoom(text);
}

document.getElementById('notify').addEventListener('click', async () => {
    const pushes = await puter.notifications.enable();
    console.log(pushes ? 'You will be notified' : 'Notifications are off');
});

The worker, at /puter-sw.js:

importScripts('https://js.puter.com/push-sw.js');

Let Members Notify Each Other

A member's share connects them with the creator only, so a member can't reach the other members through it. When every member should hear about every message, whoever sent it, give each member a persistent subscription to the room's messages, with a handler that Puter runs for them even while your app is closed. The handler calls notify() for its own member, so it needs no share. Use this in place of notifyRoom().

Publish the handler once, signed in to your site as the app's owner, with puter.events.handlers.publish(). To skip the publish, pass the same function as handler to each member's onPersistent() call instead, which stores it in the member's own user scope. Run Code in the Background explains handlers in more detail:

await puter.events.handlers.publish('notifyNewMessage', async ({ event, user, ctx }) => {
    const message = event.value;
    if (event.op !== 'set' || !message || message.from === ctx.me) return;

    await user.notifications.notify({
        title: `${message.from} in ${ctx.roomTitle}`.slice(0, 120),
        text: String(message.text).slice(0, 240),
        channel: 'chat',
        group: `room:${ctx.roomId}`,
        target: `/rooms/${ctx.roomId}`,
        data: { roomId: ctx.roomId },
    });
});

Each member, the creator included, subscribes to the room's messages with puter.events.onPersistent(), naming the handler. Running a handler while the member is away needs their permission, which puter.perms.request() asks for with the backgroundEvents resource. Call this from the "Notify me" button, after puter.notifications.enable():

async function subscribeToRoom () {
    if (!await puter.perms.request('backgroundEvents')) return false;

    const subject = handle ? `kv:${handle}:msg:*` : `kv:${puter.appID}:${prefix}msg:*`;
    const subs = await puter.events.list();
    const subscribed = subs.some((sub) => sub.subject === subject
        && sub.handlerName === 'notifyNewMessage' && sub.suspendedReason !== 'permission_revoked');
    if (subscribed) return true;

    const { roomId, title } = await room.get('meta');
    await puter.events.onPersistent({
        subject,
        handlerName: 'notifyNewMessage',
        includeValue: true,
        context: { me: user.username, roomId, roomTitle: title },
    });
    return true;
}

The me check in the handler skips the member's own messages. When the creator removes a member, or the member leaves, the member's subscription stops on its own.

← All recipes