unreads_ack

Set your read position in one channel or thread. Use it when the user opens a conversation or scrolls to the latest message, so unread and mention counts go back to zero.

Request

{
  "cmd": "unreads_ack",
  "channel": "general",
  "message_id": "8f14e45f-ceea-467a-9575-3d3b4c1b2a10"
}

Field	Type	Required	Description
channel	string	One of channel or thread_id	Channel to mark as read.
thread_id	string	One of channel or thread_id	Thread to mark as read. If you also send channel, it must be the thread’s parent forum.
message_id	string	No	Mark everything up to and including this message as read. Leave it out to mark the whole conversation as read.

The read position is the timestamp of the chosen message. Without message_id, the server uses the newest message, or the current time if the conversation is empty.

• The new position replaces the old one. Acknowledging an older message moves your position back and makes later messages unread again.
• Every acknowledgement resets ping_count to 0.

Response

{
  "cmd": "unreads_ack",
  "channel": "general",
  "last_viewed": 1788624000
}

last_viewed is the new read position in Unix seconds. A thread acknowledgement has thread_id instead of channel.

Every open connection of your account, including this one, also receives an unreads_update frame with the same fields. Use it to keep your other devices in sync:

{
  "cmd": "unreads_update",
  "channel": "general",
  "last_viewed": 1788624000
}

On the calling connection, unreads_update arrives before the unreads_ack response. No one else is notified.

Permissions

You need to be able to view the channel, or the thread’s parent forum. The command still works while you are timed out.

Errors

val	When
Channel or thread_id is required	You sent neither channel nor thread_id.
Channel not found	The channel doesn’t exist.
Thread not found	No thread has this thread_id.
Thread does not belong to this channel	channel is not the thread’s parent forum.
Messages must be sent inside a thread in forum channels	channel is a forum. Acknowledge its threads with thread_id.
This channel does not support chat	The channel type has no messages.
Access denied to this channel	You can’t view the channel.
You do not have permission to view this thread	You can’t view the thread’s parent forum.
Message not found	No message has this message_id in the conversation.
Invalid stored message	The newest stored message could not be read.
Unable to save read state	The server could not write your read state to storage.
Validation message	A field is not a string, for example message_id: Expected string, received number.

See also

• unreads_get
• Read state and mentions