GET /messages

This endpoint is the primary way to fetch a messages. It is used by all official Zulip clients (e.g. the web, desktop, mobile, and terminal clients) as well as many bots, API clients, backup scripts, etc.

Most queries will specify a narrow filter, to fetch the messages matching any supported search query. If not specified, it will return messages corresponding to the user's combined feed. There are two ways to specify which messages matching the narrow filter to fetch:

A range of messages, described by an anchor message ID (or a string-format specification of how the server should computer an anchor to use) and a maximum number of messages in each direction from that anchor.
A rarely used variant (message_ids) where the client specifies the message IDs to fetch.

The server returns the matching 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.

Note that a user's message history does not contain messages sent to channels before they subscribe, and newly created bot users are not usually subscribed to any channels.

We recommend requesting at most 1000 messages in a batch, 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.

Changes: The message_ids option is new in Zulip 10.0 (feature level 300).

Servers

https://{subdomain}.zulipchat.com/api/v1
{server}/api/v1
https://chat.zulip.org/api/v1

Query parameters

Name	Type	Required	Description
`anchor_date`	String	No	The date or datetime to use for finding the anchor message when `anchor` is `date`. Accepted formats include ISO 8601 date-only strings (e.g. `2005-04-18`) as well as full datetime strings (e.g. `2005-04-18T12:34:56Z`). If only a date is provided, the datetime is set to midnight (00:00) on that day in UTC. If no timezone is provided, UTC is assumed. Changes: New in Zulip 12.0 (feature level 445).
`narrow`		No	The narrow where you want to fetch the messages from. See how to construct a narrow. Note that many narrows, including all that lack a `channel`, `channels`, `stream`, or `streams` operator, search the user's personal message history. See searching shared history for details. For example, if you would like to fetch messages from all public channels instead of only the user's message history, then a specific narrow for messages sent to all public channels can be used: `{"operator": "channels", "operand": "public"}`. Newly created bot users are not usually subscribed to any channels, so bots using this API should either be subscribed to appropriate channels or use a shared history search narrow with this endpoint. Changes: See changes section of search/narrow filter documentation.
`use_first_unread_anchor`	Boolean	No	Legacy way to specify `"anchor": "first_unread"` in Zulip 2.1.x and older. Whether to use the (computed by the server) first unread message matching the narrow as the `anchor`. Mutually exclusive with `anchor`. Changes: Deprecated in Zulip 3.0 (feature level 1) and replaced by `"anchor": "first_unread"`. Default value: false
`num_before`	Integer	No	The number of messages with IDs less than the anchor to retrieve. Required if `message_ids` is not provided.
`num_after`	Integer	No	The number of messages with IDs greater than the anchor to retrieve. Required if `message_ids` is not provided.
`allow_empty_topic_name`	Boolean	No	Whether the client supports processing the empty string as a topic in the topic name fields in the returned data, including in returned edit_history data. If `false`, the server will use the value of `realm_empty_topic_display_name` found in the `POST /register` response instead of empty string to represent the empty string topic in its response. Changes: New in Zulip 10.0 (feature level 334). Previously, the empty string was not a valid topic. Default value: false
`apply_markdown`	Boolean	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. See Markdown message formatting for details on Zulip's HTML format. Default value: true
`anchor`	String	No	Integer message ID to anchor fetching of new messages. Supports special string values for when the client wants the server to compute the anchor to use: `newest`: The most recent message. `oldest`: The oldest message. `first_unread`: The oldest unread message matching the query, if any; otherwise, the most recent message. `date`: The first message on or after the datetime indicated by the `anchor_date`, if any; otherwise, the most recent message. Changes: The `date` value is new in Zulip 12.0 (feature level 445). String values are new in Zulip 3.0 (feature level 1). The `first_unread` functionality was supported in Zulip 2.1.x and older by not sending `anchor` and using `use_first_unread_anchor`. In Zulip 2.1.x and older, `oldest` can be emulated with `"anchor": 0`, and `newest` with `"anchor": 10000000000000000` (that specific large value works around a bug in Zulip 2.1.x and older in the `found_newest` return value).
`include_anchor`	Boolean	No	Whether a message with the specified ID matching the narrow should be included. Changes: New in Zulip 6.0 (feature level 155). Default value: true
`client_gravatar`	Boolean	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. The `client_gravatar` field is set to `true` if clients can compute their own gravatars. Changes: The default value of this parameter was `false` prior to Zulip 5.0 (feature level 92). Default value: true
`message_ids`		No	A list of message IDs to fetch. The server will return messages corresponding to the subset of the requested message IDs that exist and the current user has access to, potentially filtered by the narrow (if that parameter is provided). It is an error to pass this parameter as well as any of the parameters involved in specifying a range of messages: `anchor`, `include_anchor`, `use_first_unread_anchor`, `num_before`, and `num_after`. Changes: New in Zulip 10.0 (feature level 300). Previously, there was no way to request a specific set of messages IDs.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.