Messages are sent using the write token of the document. For that purpose, the write token of an inbox document is shared with all potential senders. The read token is kept secret by the owner.
Messages are small JSON documents of up to 4096 bytes. They may contain some data, or refer to other documents or blobs.
Every message has an 16-hexdigit message ID, which is randomly generated by the sender. Messages can be updated by sending a message with the same ID, and a newer revision field ("#": ...). The revision is usually a Unix timestamp in milliseconds since epoch. If no revision field is present, the revision is assumed to be 0.
The owner can use an inbox document like any other document. To read the messages, it loads the document, and typically removes all processed messages from the list.
Using Backend.js, a message can be sent as follows:
Adds or merges a message on an inbox document. The message ID must be a 16-hexdigit token.
Delete a message
200 if the message was deleted or did not exists
403 if the document is not an inbox
Inbox write token
Removes a message.
Message removal should be used with care. First of all, the message may already have been read by the recipient. Second, message removal is not a forward operation: after the removal, an old version of the message may get merged — either by a valid request, a concurrent request, or a (malicious) replay of a previous request.
Nevertheless message removal is useful and safe when used properly.
If UDP is enabled, the following requests are available.
Send a message
Adds or merges a message on an inbox document, and responds with an "M" message upon success.
If the document is not an inbox, "N" is returned.
Delete a message
Removes a message. See above for a discussion about message removal.