How to show a system message only to a specific user

As a chat admin, you may want to send a user in a conversation an update with information that only applies to them. For example, if you’re operating a marketplace chat, you might want to alert one user that they’ve received a new bid, and send another user a confirmation that their bid has been accepted.

System messages allow you to send neutrally rendered messages to a conversation without having to be a participant or guest in that conversation.

By default, system messages show up for all users in a conversation. However, you can use custom data and message filters to show a system message only to selected participants, rather than to all users in a conversation.

Here’s how to show a system message only to specific users.

1. Set a custom property on a message

Begin by specifying, for the system message that you only want to show to one user, who should be able to see that system message. You can do this by setting a custom property on the system message that contains the user ID of the user who should see the message.

For example, you could set a custom object named visibleTo. This visibleTo object could then contain the user ID of the user to whom you want to show the system message, as follows:

"custom": {
    "visibleTo": "<USER_ID>"
}

In this example, you would replace <USER_ID> with the ID of the user to whom you want to show the system message.

2. Specify a message filter

Next, specify a message filter to filter for your custom message property. With a message filter, you can show the relevant system messages only to the user with the ID that you specified in the custom message property.

For example, to create a chatbox and set a message filter that shows the user only those messages that:

• have no visibleTo field set (which will be the case for almost all messages); or
• have a visibleTo field set to the user ID of the current user;

you could use the following code snippet:

const chatbox = session.createChatbox({
    messageFilter: ["any", [ // The "any" filter matches messages that match any of the filters within it.
        {custom: {visibleTo: "!exists"}}, // A filter that matches messages where the custom value "visibleTo" is not set.
        {custom: {visibleTo: ["==", "<USER_ID>"]} // A filter that matches messages where the custom value "visibleTo" matches the user ID.
    ]]
})

In this code snippet, replace <USER_ID> with the user ID of the current user.

For more information on how to send a system message, check out the REST API docs.

Security

If you filter system messages in this way, be aware that even if filtered messages aren’t shown, they're still sent to the browser of everyone in the conversation. That means that users other than the specified user ID could in principle still access those system messages. For that reason, avoid sending sensitive data—such as authentication tokens—in system messages that are filtered to be only shown to a single user.

That’s it! Using custom data and message filters, you can now send system messages that only show up for a specific user in a conversation.

Do you have any further questions? We’re happy to help. Get in touch.