Message receipts and reactions

Message receipts enable users to track delivery of messages in a channel. Receipts are most useful in direct one-to-one chats, or in small group chats to indicate that users have read a particular message. They're not commonly used in high-occupancy chats, or in broadcasts with many users.

There are two kinds of receipts:

  • Delivered receipts indicate that the message has been delivered to a user
  • Read receipts indicate that a user has read the message
User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

Add a receipt​

Use the addMessageAction method to add a receipt on a channel by passing the timetoken of a message. Set the value to message_delivered or message_read to indicate if the message was delivered and received by the user, or if it was read.

Your application needs to implement client-side logic to determine when receipts should be added. Add receipts when the user comes and goes from a channel, or periodically after every few messages. For efficiency, assume that when a message is marked read, all messages published before that message are also read by the user.

pubnub.addMessageAction(
  {
    channel: 'ch-1'
    messageTimetoken: '15610547826970040',
    action: {
      type: 'receipt',
      value: 'read',
    },
  },
  function(status, response) {

  }
);

Remove a receipt​

Use the removeMessageAction() method to remove a receipt from a message by providing an actionTimetoken and messageTimetoken for the original message.

pubnub.removeMessageAction(
  {
    channel: 'ch-1'
    messageTimetoken: '15610547826970040',
    actionTimetoken: '15610547826999081',
  },
  function(status, response) {

  }
);

Fetch receipts in channel​

Receipts are stored in history alongside messages when they are added by a user.

Use the getMessageActions method to fetch receipts in a channel. The method works much like other PubNub history methods, and allows you to pass a start and end timetoken and fetch all message reactions that were published during that time. Your app can parse through these actions and update the message state locally.

pubnub.getMessageActions(
  {
    channel: 'chats.room1',
    start: '15901706735798836',
    end: '15901706735370016',
    limit: 100,
  },
  function(status, response) {
    console.log(status, response);
  }
);

Fetch messages with receipts​

Use the fetchMessages method with the includeMessageActions parameter set to fetch past messages in a channel along with receipts that were added to those messages. When you're fetching messages with their receipts, you can only fetch on a single channel at a time.

Message Receipt Events​

PubNub triggers events to notify clients when receipts are added to or removed from messages. To receive these events, clients should be subscribed to the channel, and add a messageAction listener in the code.

EventDescription
Message Reaction Added
Generated when a message reaction is added to a message.
Message Reaction Removed
Generated when a message reaction is removed from a message.

Message Reaction Added:

{
   "channel":"my_channel",
   "subscription":null,
   "timetoken":"15610547826970040",
   "publisher":"user-1",
   "message":{
      "source":"actions",
      "version":"1.0",
      "action":"added",
      "data":{
         "type":"receipt",
         "value":"read",
         "messageTimetoken":"15610547826970040",
         "actionTimetoken":"15610547826999081"
      }
show all 17 lines

Message Reaction Removed:

{
   "channel":"my_channel",
   "subscription":null,
   "timetoken":"15610547826970040",
   "publisher":"user-1",
   "message":{
      "source":"actions",
      "version":"1.0",
      "action":"removed",
      "data":{
         "type":"receipt",
         "value":"read",
         "messageTimetoken":"15610547826970040",
         "actionTimetoken":"15610547826999081"
      }
show all 17 lines
Last updated on
On this page