Home

Integrations

Interactive bots (beta)

REST API

Messages

Streams

Users

Server & organizations

Real-time events

Specialty endpoints

Back to uKnowva Messenger

Get messages

Fetch message history from a uKnowva Messenger server.

GET https://aniket.chat.convergenceservices.in/api/v1/messages

This GET /api/v1/messages endpoint is the primary way to fetch message history from a uKnowva Messenger server. It is useful both for uKnowva Messenger 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 uKnowva Messenger'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

  • Python
  • JavaScript
  • curl

#!/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)

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


curl -X GET https://aniket.chat.convergenceservices.in/api/v1/messages \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -d "anchor=42" \
    -d "use_first_unread_anchor=false" \
    -d "num_before=3" \
    -d "num_after=14" \
    -d "narrow=[{\"operator\":\"stream\", \"operand\":\"party\"}]" \

Arguments

Argument Example Required Description
anchor 42 No

The message ID to fetch messages near. Required unless use_first_unread_anchor is set to true.
use_first_unread_anchor true No

Whether to use the (computed by the server) first unread message matching the narrow as the anchor. Mutually exclusive with anchor. Defaults to false.
num_before 4 Yes

The number of messages with IDs less than the anchor to retrieve.
num_after 8 Yes

The number of messages with IDs greater than the anchor to retrieve.
narrow [{"operator":"sender","operand":null}] No

The narrow where you want to fetch the messages from. See how to construct a narrow. Defaults to [].
client_gravatar true No

Whether the client supports computing gravatars URLs. If enabled, avatar_url will be included in the response only if there is a Zulip avatar, and will be null for users who are using gravatar as their avatar. This option significantly reduces the compressed size of user data, since gravatar URLs are long, random strings and thus do not compress well. Defaults to false.
apply_markdown false No

If true, message content is returned in the rendered HTML format. If false, message content is returned in the raw markdown-format text that user entered. Defaults to true.

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 uKnowva Messenger 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 uKnowva Messenger "client" string, describing what uKnowva Messenger 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 uKnowva Messenger 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"
}