Home

Integrations

Interactive bots (beta)

REST API

Messages

Streams

Users

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

Update personal message flags

Add or remove personal message flags like read and starred on a collection of message IDs.

POST https://zulip.dioco.io/api/v1/messages/flags

For updating the read flag on common collections of messages, see also the special endpoints for marking message as read in bulk.

Usage examples

  • Python
  • JavaScript
  • curl

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Add the "read" flag to the messages with IDs in "message_ids"
request = {
    'messages': message_ids,
    'op': 'add',
    'flag': 'read',
}
result = client.update_message_flags(request)
# Remove the "starred" flag from the messages with IDs in "message_ids"
request = {
    'messages': message_ids,
    'op': 'remove',
    'flag': 'starred',
}
result = client.update_message_flags(request)
print(result)

More examples and documentation can be found here.

const Zulip = require('zulip-js');

// Pass the path to your zuliprc file here.
const config = { zuliprc: 'zuliprc' };

Zulip(config).then(async (client) => {
    // Add the "read" flag to the messages with IDs in "message_ids"
    const addflag = {
        messages: message_ids,
        flag: "read",
    };
    return await client.messages.flags.add(addflag);
}).then(console.log).catch(console.err);

Zulip(config).then(async (client) => {
    // Remove the "starred" flag from the messages with IDs in "message_ids"
    const removeflag = {
        messages: message_ids,
        flag: "starred",
    };
    return await client.messages.flags.remove(removeflag);
}).then(console.log).catch(console.err);


curl -sSX POST https://zulip.dioco.io/api/v1/messages/flags \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode messages='[4, 8, 15]' \
    -d 'op=add' \
    -d 'flag=read'

Parameters

messages required

Example: [4, 8, 15]

An array containing the IDs of the target messages.

op required

Example: add

Whether to add the flag or remove it.

Must be one of: add, remove.

flag required

Example: read

The flag that should be added/removed.

Available Flags

Flag Purpose
read Whether the user has read the message. Messages start out unread (except for messages the user themself sent using a non-API client) and can later be marked as read.
starred Whether the user has starred this message.
collapsed Whether the user has collapsed this message.
mentioned Whether the current user was mentioned by this message, either directly or via a user group. Not editable.
wildcard_mentioned Whether this message contained wildcard mention like @all. Not editable.
has_alert_word Whether the message contains any of the current user's configured alert words. Not editable.
historical True for messages that the user did not receive at the time they were sent but later was added to the user's history (E.g. because they starred or reacted to a message sent to a public stream before they subscribed to that stream). Not editable.

Response

Return values

  • messages: An array with the IDs of the modified messages.

Example response

A typical successful JSON response may look like:

{
    "messages": [
        4,
        18,
        15
    ],
    "msg": "",
    "result": "success"
}