POST /register

This powerful endpoint can be used to register a Zulip "event queue" (subscribed to certain types of "events", or updates to the messages and other Zulip data the current user has access to), as well as to fetch the current state of that data.

(register also powers the call_on_each_event Python API, and is intended primarily for complex applications for which the more convenient call_on_each_event API is insufficient).

This endpoint returns a queue_id and a last_event_id; these can be used in subsequent calls to the "events" endpoint to request events from the Zulip server using long-polling.

The server will queue events for up to idle_queue_timeout_secs seconds of inactivity. After that timeout, your event queue will be garbage-collected. The server will send heartbeat events every minute, which makes it easy to implement a robust client that does not miss events unless the client loses network connectivity with the Zulip server for longer than the configured timeout.

Once the server garbage-collects your event queue, the server will return an error with a code of BAD_EVENT_QUEUE_ID if you try to fetch events from the event queue. Your software will need to handle that error condition by re-initializing itself (e.g. this is what triggers your browser reloading the Zulip web app when your laptop comes back online after being offline for more than idle_queue_timeout_secs seconds).

When prototyping with this API, we recommend first calling register with no event_types parameter to see all the available data from all supported event types. Before using your client in production, you should set appropriate event_types and fetch_event_types filters so that your client only requests the data it needs. A few minutes doing this often saves 90% of the total bandwidth and other resources consumed by a client using this API.

See the events system developer documentation if you need deeper details about how the Zulip event queue system works, avoids clients needing to worry about large classes of potentially messy races, etc.

Changes: New in Zulip 12.0 (feature level 481), the idle_queue_timeout request parameter and idle_queue_timeout_secs response field were added to allow clients to configure how long the server keeps an event queue alive during inactivity.

Removed dense_mode setting in Zulip 10.0 (feature level 364) as we now have web_font_size_px and web_line_height_percent settings for more control.

Before Zulip 7.0 (feature level 183), the realm_community_topic_editing_limit_seconds property was returned by the response. It was removed because it had not been in use since the realm setting move_messages_within_stream_limit_seconds was introduced in feature level 162.

In Zulip 7.0 (feature level 163), the realm setting email_address_visibility was removed. It was replaced by a user setting with a realm user default, with the encoding of different values preserved. Clients can support all versions by supporting the current API and treating every user as having the realm's email_address_visibility value.

Servers

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

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"

Request body fields

Name	Type	Required	Description
`narrow[]`	Array	No	A JSON-encoded array of arrays of length 2 indicating the narrow filter(s) for which you'd like to receive events for. For example, to receive events for direct messages (including group direct messages) received by the user, one can use `"narrow": [["is", "dm"]]`. Unlike the API for fetching messages, this narrow parameter is simply a filter on messages that the user receives through their channel subscriptions (or because they are a recipient of a direct message). This means that a client that requests a `narrow` filter of `[["channel", "Denmark"]]` will receive events for new messages sent to that channel while the user is subscribed to that channel. The client will not receive any message events at all if the user is not subscribed to `"Denmark"`. Newly created bot users are not usually subscribed to any channels, so bots using this API need to be subscribed to any channels whose messages you'd like them to process using this endpoint. See the `all_public_streams` parameter for how to process all public channel messages in an organization. Changes: See changes section of search/narrow filter documentation.
`idle_queue_timeout`		No	At least how long (in seconds) the server should keep the event queue alive when the client is not polling. If the client does not poll before this timeout, the queue will eventually be garbage-collected. Alternatively, the string `"mobile"` can be passed to use the server's recommended timeout for mobile clients. This is currently 12 hours, but may change in the future. If not specified, the server uses a default of 10 minutes. The maximum allowed value is 7 days. Changes: New in Zulip 12.0 (feature level 481).
`apply_markdown`	Boolean	No	Set to `true` if you would like the content to be rendered in HTML format (otherwise the API will return the raw text that the user entered) Default value: false
`all_public_streams`	Boolean	No	Whether you would like to request message events from all public channels. Useful for workflow bots that you'd like to see all new messages sent to public channels. (You can also subscribe the user to private channels). Default value: false
`fetch_event_types[]`	Array	No	Same as the `event_types` parameter except that the values in `fetch_event_types` are used to fetch initial data. If `fetch_event_types` is not provided, `event_types` is used and if `event_types` is not provided, this parameter defaults to `null`. Event types not supported by the server are ignored, in order to simplify the implementation of client apps that support multiple server versions.
`include_subscribers`	String	No	Whether each returned channel object should include a `subscribers` field containing a list of the user IDs of its subscribers. Client apps supporting organizations with many thousands of users should not pass `true`, because the full subscriber matrix may be several megabytes of data. The `partial` value, combined with the `subscriber_count` and fetching subscribers for individual channels as needed, is recommended to support client app features where channel subscriber data is useful. If a client passes `partial` for this parameter, the server may, for some channels, return a subset of the channel's subscribers in the `partial_subscribers` field instead of the `subscribers` field, which always contains the complete set of subscribers. The server guarantees that it will always return a `subscribers` field for channels with fewer than 250 total subscribers. When returning a `partial_subscribers` field, the server guarantees that all bot users and users active within the last 14 days will be included. For other cases, the server may use its discretion to determine which channels and users to include, balancing between payload size and usefulness of the data provided to the client. Passing `true` in an unauthenticated request is an error. Changes: The `partial` value is new in Zulip 11.0 (feature level 412). Before Zulip 6.0 (feature level 149), this parameter was silently ignored and processed as though it were `false` in unauthenticated requests. New in Zulip 2.1.0. Valid values: `"partial"` `"false"` `"true"` Default value: "false"
`event_types[]`	Array	No	A JSON-encoded array indicating which types of events you're interested in. Values that you might find useful include: message (messages) subscription (changes in your subscriptions) realm_user (changes to users in the organization and their properties, such as their name). If you do not specify this parameter, you will receive all events, and have to filter out the events not relevant to your client in your client code. For most applications, one is only interested in messages, so one specifies: `"event_types": ["message"]` Event types not supported by the server are ignored, in order to simplify the implementation of client apps that support multiple server versions.
`presence_history_limit_days`	Integer	No	Limits how far back in time to fetch user presence data. If not specified, defaults to 14 days. A value of N means that the oldest presence data fetched will be from at most N days ago. Changes: New in Zulip 10.0 (feature level 288).
`client_capabilities`	Object	No	Dictionary containing details on features the client supports that are relevant to the format of responses sent by the server. `notification_settings_null`: Boolean for whether the client can handle the current API with `null` values for channel-level notification settings (which means the channel is not customized and should inherit the user's global notification settings for channel messages). Changes: New in Zulip 2.1.0. In earlier Zulip releases, channel-level notification settings were simple booleans. `bulk_message_deletion`: Boolean for whether the client's handler for the `delete_message` event type has been updated to process the new bulk format (with a `message_ids`, rather than a singleton `message_id`). Otherwise, the server will send `delete_message` events in a loop. Changes: New in Zulip 3.0 (feature level 13). This capability is for backwards-compatibility; it will be required in a future server release. `user_avatar_url_field_optional`: Boolean for whether the client required avatar URLs for all users, or supports using `GET /avatar/{user_id}` to access user avatars. If the client has this capability, the server may skip sending a `avatar_url` field in the `realm_user` at its sole discretion to optimize network performance. This is an important optimization in organizations with 10,000s of users. Changes: New in Zulip 3.0 (feature level 18). `stream_typing_notifications`: Boolean for whether the client supports channel typing notifications. Changes: New in Zulip 4.0 (feature level 58). This capability is for backwards-compatibility; it will be required in a future server release. `user_settings_object`: Has no effect with modern servers. Previously, this was a boolean for whether the client supported the modern `user_settings` event type and the top-level `user_settings` object in this endpoint's response. Changes: Prior to Zulip 12.0 (feature level 439), if false, the server would additionally send the legacy `update_global_notifications` and `update_display_settings` event types, if requested. New in Zulip 5.0 (feature level 89). Because the feature level 89 API changes were merged together, clients could safely make a request with this client capability, and also request all three event types (`user_settings`, `update_display_settings`, and `update_global_notifications`), and then use the `zulip_feature_level` in this endpoint's response or the presence/absence of a `user_settings` key to determine where to look for the data. `linkifier_url_template`: Boolean for whether the client accepts linkifiers that use RFC 6570 compliant URL templates for linkifying matches. If false or unset, then the `realm_linkifiers` array in the `/register` response will be empty if present, and no `realm_linkifiers` events will be sent to the client. Changes: New in Zulip 7.0 (feature level 176). This capability is for backwards-compatibility. `user_list_incomplete`: Boolean for whether the client supports not having an incomplete user database. If true, then the `realm_users` array in the `register` response will not include data for inaccessible users and clients of guest users will not receive `realm_user op:add` events for newly created users that are not accessible to the current user. Changes: New in Zulip 8.0 (feature level 232). This capability is for backwards-compatibility. `include_deactivated_groups`: Boolean for whether the client can handle deactivated user groups by themselves. If false, then the `realm_user_groups` array in the `/register` response will only include active groups, clients will receive a `remove` event instead of `update` event when a group is deactivated and no `update` event will be sent to the client if a deactivated user group is renamed. Changes: New in Zulip 10.0 (feature level 294). This capability is for backwards-compatibility. `archived_channels`: Boolean for whether the client supports processing archived channels in the `stream` and `subscription` event types. If `false`, the server will not include data related to archived channels in the `register` response or in events. Changes: New in Zulip 10.0 (feature level 315). This allows clients to access archived channels, without breaking backwards-compatibility for existing clients. `empty_topic_name`: Boolean for whether the client supports processing the empty string as a topic name. Clients not declaring this capability will be sent the value of `realm_empty_topic_display_name` found in the POST /register response instead of the empty string wherever topic names appear in the register response or events involving topic names. Changes: New in Zulip 10.0 (feature level 334). Previously, the empty string was not a valid topic name. `simplified_presence_events`: Boolean for whether the client supports receiving the `presence` event type with user presence data in the modern format. If true, the server will send these events with the `presences` field that has the user presence data in the modern format. Otherwise, these event will contain fields with legacy format user presence data. Changes: New in Zulip 11.0 (feature level 419). `individual_emoji_changes`: Boolean for whether the client supports receiving the `realm_emoji/add` and `realm_emoji/edit` event types. If true, the server will send individual `realm_emoji/add` events when a custom emoji is added, and `realm_emoji/edit` events when a custom emoji's properties are changed (e.g., deactivated). Otherwise, the server will send the legacy `realm_emoji/update` event containing all custom emoji for the organization. Changes: New in Zulip 12.0 (feature level 491).
`slim_presence`	Boolean	No	If `true`, the `presences` object returned in the response will be keyed by user ID and the entry for each user's presence data will be in the modern format. Changes: New in Zulip 3.0 (no feature level; API unstable). Default value: false
`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. The default value is `true` for authenticated requests and `false` for unauthenticated requests. Passing `true` in an unauthenticated request is an error. Changes: Before Zulip 6.0 (feature level 149), this parameter was silently ignored and processed as though it were `false` in unauthenticated requests.

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.