Messaging
Messaging allows users to send cross-webstrate messages between users, even when a user isn’t online. It’s basically emails for Webstrates.
Sending messages
To send a message to a user (or several), call
webstrate.message(message, recipients);
The message object can be any serializable JavaScript object (string, number, array, object…).
recipients can be either a userId (username:provider, e.g. kbadk:github), a current or
recently used clientId, or a list containing a combination of the former two.
webstrate.message("Hello, world!", "kbadk:github")
and
webstrate.message({ foo: ["quux", "bar"] }, ["B1bvxz0DNZ", "kbadk:github"])
are therefore both legal.
Only logged in users can send and receive messages.
Receiving messages
Whenever a message is sent, it’ll be delivered to all connected clients as well as saved on the
server. Listening for messages can be done using the messageReceived event on the global webstrate
object.
webstrate.on('messageReceived', function(message, senderId, messageId) {
// message being the message object (e.g. "Hello, world!"), senderId being the sending
// userId (e.g. "kbadk:github", never "B1bvxz0DNZ"), and messageId a random string
// assigned to the message by the server (e.g. "rkwJJCP4Z").
});
This callback would also get triggered shortly after the loaded event has triggered in a document,
once for every message stored. As long as messages have not been deleted, these events will keep
getting triggered, until they expire. Messages automatically expire after 30 days.
Additionally, all messages are accessible in webstrate.messages.
Deleting messages
To prevent the same messages from getting triggered on every load, they can be deleted, either by deleting all messages:
webstrate.deleteMessages();
Or by deleting single messages by messageId:
webstrate.deleteMessage(messageId);
It’s also possible to listen for deletions using the messageDeleted event.
webstrate.on('messageDeleted', function(messageId) {
// a message has been deleted.
});
A word on message persistence: Messages aren't automatically deleted from the server after they have been received by a client, because we won't know if any of the receiving webstrates handles the messages appropriately.
One can easily imagine a scenario where messages were intended for consumption in Webstrate A, but the recipient was only connected to Webstrate B at the time. As messages are addressed to users (not webstrates), Webstrate B would end up consuming the messages intended for Webstrate A as long as the user remained connected to the Webstrate B.
Users are therefore required to manually delete messages to acknowledge that they have indeed handled the messages appropriately.