Get messages

Fetch message history from a Zulip server.

GET https://chat.zymocosm.com/api/v1/messages

This GET /api/v1/messages endpoint is the primary way to fetch message history from a Zulip server. It is useful both for Zulip clients (e.g. the web, desktop, mobile, and terminal clients) as well as bots, API clients, backup scripts, etc.

By specifying a narrow filter, you can use this endpoint to fetch the messages matching any search query that is supported by Zulip's powerful full-text search backend.

When a narrow is not specified, it can be used to fetch a user's message history (We recommend paginating to 1000 messages at a time).

In either case, you specify an anchor message (or ask the server to calculate the first unread message for you and use that as the anchor), as well as a number of messages before and after the anchor message. The server returns those messages, sorted by message ID, as well as some metadata that makes it easy for a client to determine whether there are more messages matching the query that were not returned due to the num_before and num_after limits.

We recommend using num_before <= 1000 and num_after <= 1000 to avoid generating very large HTTP responses. A maximum of 5000 messages can be obtained per request; attempting to exceed this will result in an error.

Usage examples

#!/usr/bin/env python3

import zulip

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

# Get the 3 last messages sent by "iago@zulip.com" to the stream "Verona"
request = {
    'use_first_unread_anchor': True,
    'num_before': 3,
    'num_after': 0,
    'narrow': [{'operator': 'sender', 'operand': 'iago@zulip.com'},
               {'operator': 'stream', 'operand': 'Verona'}],
    'client_gravatar': True,
    'apply_markdown': True
}  # type: Dict[str, Any]
result = client.get_messages(request)
print(result)

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);

curl -sSX GET -G https://chat.zymocosm.com/api/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d 'anchor=42' \
    -d 'use_first_unread_anchor=true' \
    -d 'num_before=4' \
    -d 'num_after=8' \
    --data-urlencode narrow='[{"operand": "Denmark", "operator": "stream"}]'

Arguments

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.
  • 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".
  • subject_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.)
  • 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:

{
    "anchor": 21,
    "found_anchor": true,
    "found_newest": true,
    "messages": [
        {
            "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
            "client": "populate_db",
            "content": "<p>Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.</p>",
            "content_type": "text/html",
            "display_recipient": [
                {
                    "email": "hamlet@zulip.com",
                    "full_name": "King Hamlet",
                    "id": 4,
                    "is_mirror_dummy": false,
                    "short_name": "hamlet"
                },
                {
                    "email": "iago@zulip.com",
                    "full_name": "Iago",
                    "id": 5,
                    "is_mirror_dummy": false,
                    "short_name": "iago"
                },
                {
                    "email": "prospero@zulip.com",
                    "full_name": "Prospero from The Tempest",
                    "id": 8,
                    "is_mirror_dummy": false,
                    "short_name": "prospero"
                }
            ],
            "flags": [
                "read"
            ],
            "id": 16,
            "is_me_message": false,
            "reactions": [],
            "recipient_id": 27,
            "sender_email": "hamlet@zulip.com",
            "sender_full_name": "King Hamlet",
            "sender_id": 4,
            "sender_realm_str": "zulip",
            "sender_short_name": "hamlet",
            "subject": "",
            "subject_links": [],
            "submessages": [],
            "timestamp": 1527921326,
            "type": "private"
        },
        {
            "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
            "client": "populate_db",
            "content": "<p>Wait, is this from the frontend js code or backend python code</p>",
            "content_type": "text/html",
            "display_recipient": "Verona",
            "flags": [
                "read"
            ],
            "id": 21,
            "is_me_message": false,
            "reactions": [],
            "recipient_id": 20,
            "sender_email": "hamlet@zulip.com",
            "sender_full_name": "King Hamlet",
            "sender_id": 4,
            "sender_realm_str": "zulip",
            "sender_short_name": "hamlet",
            "stream_id": 5,
            "subject": "Verona3",
            "subject_links": [],
            "submessages": [],
            "timestamp": 1527939746,
            "type": "stream"
        }
    ],
    "msg": "",
    "result": "success"
}