Read receipts

Read receipts show if channel members have viewed a message.

Required setup

Read Receipts requires Unread Message Count. First, set the last read timetoken for each user on a channel.

Get read receipts

onReadReceiptReceived() listens for incoming receipt events on a channel. The callback is invoked each time a member updates their last read message.

Not available for public chats

Read receipts are disabled in public chats.

Control which channel types emit read receipts

emitReadReceiptEvents in Chat.init() controls which channel types emit receipt events. By default, direct and group channels emit receipts and public channels do not. Refer to Configuration for details.

The ReadReceipt type has the following shape:

1type ReadReceipt = {
2    userId: string
3    lastReadTimetoken: string
4}

Method signature

1channel.onReadReceiptReceived(
2    callback: (receipt: ReadReceipt) => void
3): () => void

Input

* required

Parameter	Description
callback * Type: n/a Default: n/a	Callback function passed as a parameter. It defines the custom behavior to be executed when receiving a read confirmation event on the joined channel.
→ receipt * Type: ReadReceipt Default: n/a	Object containing the userId of the member who read the message and the lastReadTimetoken indicating which message they last read.

Output

Type	Description
() => void	Function you can call to stop receiving read receipt events.

Sample code

Listen for read receipt events on the support channel.

1// reference the "support" channel
2const channel = await chat.getChannel("support")
3

4const stopListening = channel.onReadReceiptReceived((receipt) => {
5    console.log(`User ${receipt.userId} last read up to timetoken ${receipt.lastReadTimetoken}`)
6})
7

8// after some time...
9stopListening()

Fetch read receipts

fetchReadReceipts() retrieves a paginated list of read receipts for all members on a channel.

The ReadReceiptsResponse type has the following shape:

1type ReadReceiptsResponse = {
2    page: {
3        next?: string
4        prev?: string
5    }
6    total: number
7    status: number
8    receipts: ReadReceipt[]
9}

Method signature

1channel.fetchReadReceipts(params?: {
2    filter?: string
3    sort?: object
4    limit?: number
5    page?: {
6        next?: string
7        prev?: string
8    }
9}): Promise<ReadReceiptsResponse>

Input

* required

Parameter	Description
params Type: object Default: n/a	Optional pagination and filtering parameters.
→ filter Type: string Default: n/a	Expression used to filter the results.
→ sort Type: object Default: n/a	Key-value pair of a property to sort by and sort direction.
→ limit Type: number Default: 100	Number of receipts to return. The default (and maximum) value is 100.
→ page Type: object Default: n/a	Object used for pagination.
→ next Type: string Default: n/a	Token for forward pagination.
→ prev Type: string Default: n/a	Token for backward pagination. Ignored if next is supplied.

Output

Parameter	Description
Promise<ReadReceiptsResponse> Type: object	Returned object containing page, total, status, and receipts.
→ page Type: object	Pagination cursors.
→ total Type: number	Total number of read receipts.
→ status Type: number	HTTP status code of the response, like 200.
→ receipts Type: ReadReceipt[]	Array of read receipts.

Sample code

Fetch all read receipts for the support channel.

1// reference the "support" channel
2const channel = await chat.getChannel("support")
3

4const { receipts, total } = await channel.fetchReadReceipts()
5console.log(`Total receipts: ${total}`)
6receipts.forEach((receipt) => {
7    console.log(`User ${receipt.userId} last read up to timetoken ${receipt.lastReadTimetoken}`)
8})

Deprecated method

Deprecated

streamReadReceipts() is deprecated. Use onReadReceiptReceived() to listen for real-time events and fetchReadReceipts() to retrieve historical data instead.

streamReadReceipts() provided read status for messages on a channel. The method fetched member read status, listened for updates, and passed receipt events to your callback.

1channel.streamReadReceipts(callback: (receipts: {
2    [key: string]: string[];
3}) => unknown): Promise<() => void>

Sample code

1// reference the "support" channel
2const channel = await chat.getChannel("support")
3

4const stopReceipts = await channel.streamReadReceipts((receipts) => {
5  // callback to handle current receipts data
6})
7

8// after some time...
9stopReceipts()