zulip/templates/zerver/api/get-messages.md

Get messages

{generate_api_description(/messages:get)}

Usage examples

{start_tabs} {tab|python}

{generate_code_example(python)|/messages:get|example}

{tab|js}

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((client) => {
    const readParams = {
        stream,
        type: 'stream',
        anchor: res.id,
        num_before: 1,
        num_after: 1,
    };

    // Fetch messages anchored around id (1 before, 1 after)
    return client.messages.retrieve(readParams);
}).then(console.log);

{tab|curl}

{generate_code_example(curl, exclude=["client_gravatar", "apply_markdown", "use_first_unread_anchor"])|/messages:get|example}

{end_tabs}

Arguments

{generate_api_arguments_table|zulip.yaml|/messages:get}

Response

Return values

When a request is successful, this endpoint returns a dictionary containing the following (in addition to the msg and result keys present in all Zulip API responses).

• anchor: the same anchor specified in the request.
• found_newest: whether the messages list includes the latest message in the narrow.
• found_oldest: whether the messages list includes the oldest message in the narrow.
• found_anchor: whether it was possible to fetch the requested anchor, or the closest in the narrow has been used.
• messages: an array of message objects, each containing the following fields:
  • avatar_url: The URL of the user's avatar.
  • client: A Zulip "client" string, describing what Zulip client sent the message.
  • content: The content/body of the message.
  • content_type: The HTTP content_type for the message content. This will be text/html or text/x-markdown, depending on whether apply_markdown was set.
  • display_recipient: Data on the recipient of the message; either the name of a stream or a dictionary containing data on the users who received the message.
  • flags: The user's message flags for the message.
  • id: The unique message ID. Messages should always be displayed sorted by ID.
  • is_me_message: Whether the message is a /me status message
  • reactions: Data on any reactions to the message.
    • emoji_code: An encoded version of the emoji's unicode codepoint.
    • emoji_name: Name of the emoji.
    • reaction_type: If the reaction uses a custom emoji, reaction_type will be set to realm_emoji.
    • user_id: The ID of the user who added the reaction. Changes: New in Zulip 2.2 (feature level 2). The user object is deprecated and will be removed in the future.
    • user: Dictionary with data on the user who added the reaction, including the user ID as the id field. Note: In the events API, this user dictionary confusing had the user ID in a field called user_id instead. We recommend ignoring fields other than the user ID. Deprecated and to be removed in a future release once core clients have migrated to use the user_id field.
  • recipient_id: A unique ID for the set of users receiving the message (either a stream or group of users). Useful primarily for hashing.
  • sender_email: The email address of the message's sender.
  • sender_full_name: The full name of the message's sender.
  • sender_id: The user ID of the message's sender.
  • sender_realm_str: A string identifier for the realm the sender is in.
  • sender_short_name: Reserved for future use.
  • stream_id: Only present for stream messages; the ID of the stream.
  • subject: The topic of the message (only present for stream messages). The name is a legacy holdover from when topics were called "subjects".
  • topic_links: Data on any links to be included in the topic line (these are generated by custom linkification filters that match content in the message's topic.) Changes: New in Zulip 2.2 (feature level 1). Previously, this field was called subject_links; clients are recommended to rename subject_links to topic_links if present for compatibility with older Zulip servers.
  • submessages: Data used for certain experimental Zulip integrations.
  • timestamp: The UNIX timestamp for when the message was sent, in UTC seconds.
  • type: The type of the message: stream or private.

Example response

A typical successful JSON response may look like:

{generate_code_example|/messages:get|fixture(200)}