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 recipients:
- Delivered receipts indicate that the message has been delivered to a user
- Read receipts indicate that a user has read the message
Adding a message receipt
addMessageAction method to add a receipt on a channel by passing the timetoken of a message. Set the value to
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. You should 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. This is a common approach in most chat applications.
Receiving receipt events
When you add a receipt is added, an event is published to all users in that channel so they can instantly show the message as read. Your application should be set up with the message actions listener to receive these events.
Fetching receipts from storage
If a user isn't present when a message action is added, they can fetch message actions from storage when they reconnect and visit that channel.
getMessageActions method to fetch receipts in a channel. The API allows you to pass a start and end timetoken and fetch all message actions that were published during that time. The app can parse through these actions from the past and update its local state accordingly.
Fetching messages with receipts
includeMessageActions flag (or
fetchActions in Swift) with the
fetchMessages() method to fetch past messages in a channel along with receipts that were added to those messages.
To fetch the 25 most recent messages in a channel, fetch messages and specify neither the
start nor the
end parameter. If there are more than 25 messages to be fetched, you can iterate through the message history by adjusting the
end timetokens to page through the full set of results.
Start and End parameters
Messages are always returned in chronological order — from oldest to newest — within the timetoken range you request.
If you specify only the
start parameter (without
end), you will receive messages older than the start timetoken value.
If you specify only the
end parameter (without
start), you will receive messages from the last (most recent) message going back to that timetoken value.
Specify values for both
end to retrieve messages between those timetokens (inclusive of the end value).
Removing a receipt from a message
removeMessageAction() to remove a receipt from a message. A receipt can only be removed by the user who added the receipt.