unreads_get

Fetch your read state for every conversation you can view. Use it after connecting to draw unread badges and mention counts in the channel list.

Request

{
  "cmd": "unreads_get"
}

No fields besides cmd.

Response

{
  "cmd": "unreads_get",
  "unreads": {
    "general": {
      "last_viewed": 1788624000,
      "unread_count": 4,
      "ping_count": 1,
      "total_messages": 812
    },
    "thread/0b7d1c2e-4f3a-4e8b-9a61-5c2d7e9f1a34": {
      "last_viewed": null,
      "unread_count": 12,
      "ping_count": 0,
      "total_messages": 12,
      "parent_channel": "projects"
    }
  }
}

unreads has one entry per conversation:

• Text and voice channels use the channel name as the key.
• Forum threads use thread/<thread_id> and add parent_channel, the forum’s name.
• Channels you can’t view, and channel types without messages, are left out.

Field	Description
last_viewed	Your read position, in Unix seconds. null if you have never acknowledged this conversation.
unread_count	Messages sent after last_viewed, not counting your own. If last_viewed is null, every message from someone else counts.
ping_count	Messages that pinged you since your last acknowledgement.
total_messages	All messages in the conversation, including yours.

This response goes to the caller only. The server doesn’t push later count changes; clients count new messages themselves and listen for unreads_update (see unreads_ack).

Permissions

Any member can call it. Only conversations you can view are included.

Errors

This command returns no errors of its own.

See also

• unreads_ack
• pings_get
• Read state and mentions