Get conversation previews

GET https://connect.suryojasvi.com/api/v1/dm_previews

Fetch a one-line preview of the most recent message in each of the user's direct message conversations, and in each channel they are subscribed to.

This is designed for rendering a chat list, where every conversation shows a snippet of its latest message. Clients generally fetch this once at startup and keep it up to date from the message events they already receive.

Channel previews are computed from the requesting user's own message history, so a channel with protected history never reveals messages sent before the user could see them.

Changes: New in Zulip 13.0 (feature level ZF-122042).

Usage examples

The -u line implements HTTP Basic authentication. See the Authorization header documentation for how to get those credentials for Zulip users and bots.

curl -sSX GET -G https://connect.suryojasvi.com/api/v1/dm_previews \
    -u EMAIL_ADDRESS:API_KEY

Parameters

This endpoint does not accept any parameters.

Response

Return values

  • previews: (object)[]

    A preview of each direct message conversation the user has participated in, ordered with the most recent conversation first.

    • user_ids: (integer)[]

      The IDs of the users in the conversation, sorted. For a conversation with only oneself, this is the requesting user's own ID.

    • max_message_id: integer

      The ID of the most recent message in the conversation.

    • sender_id: integer

      The ID of the user who sent that message.

    • timestamp: integer

      UNIX timestamp for when that message was sent, in UTC seconds.

    • preview: string

      A plain text rendering of that message, truncated to at most 120 characters.

    • is_deleted: boolean

      Whether that message was deleted by its sender, leaving only a marker where it was. Its preview is then empty, and a client shows the same marker in the chat list.

  • channel_previews: (object)[]

    The same, for each channel the user is subscribed to that has a message the user can read.

    • stream_id: integer

      The ID of the channel.

    • max_message_id: integer

      The ID of the most recent message in the channel that the user can read.

    • sender_id: integer

      The ID of the user who sent that message.

    • timestamp: integer

      UNIX timestamp for when that message was sent, in UTC seconds.

    • preview: string

      A plain text rendering of that message, truncated to at most 120 characters.

    • is_deleted: boolean

      Whether that message was deleted by its sender, leaving only a marker where it was. Its preview is then empty, and a client shows the same marker in the chat list.

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "channel_previews": [
        {
            "is_deleted": false,
            "max_message_id": 172,
            "preview": "Deploy is green",
            "sender_id": 8,
            "stream_id": 5,
            "timestamp": 1748449200
        }
    ],
    "msg": "",
    "previews": [
        {
            "is_deleted": false,
            "max_message_id": 174,
            "preview": "See you at the standup",
            "sender_id": 10,
            "timestamp": 1748452800,
            "user_ids": [
                10
            ]
        }
    ],
    "result": "success"
}