POST /users/me/presence

Update the current user's presence and fetch presence data of other users in the organization.

This endpoint is meant to be used by clients for both:

Reporting the current user's presence status ("active" or "idle") to the server.
Obtaining the presence data of all other users in the organization via regular polling.

Accurate user presence is one of the most expensive parts of any chat application (in terms of bandwidth and other resources). Therefore, it is important that clients implementing Zulip's user presence system use the modern last_update_id protocol to minimize fetching duplicate user presence data.

Client apps implementing presence are recommended to also consume presence events), in order to learn about newly online users immediately.

The Zulip server is responsible for implementing invisible mode, which disables sharing a user's presence data. Nonetheless, clients should check the presence_enabled field in user objects in order to display the current user as online or offline based on whether they are sharing their presence information.

Changes: As of Zulip 8.0 (feature level 228), if the CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE server-level setting is true, then user presence data in the response is limited to users the current user can see/access.

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
`ping_only`	Boolean	No	Whether the client is sending a ping-only request, meaning it only wants to update the user's presence `status` on the server. Otherwise, also requests the server return user presence data for all users in the organization, which is further specified by the `last_update_id` parameter. Default value: false
`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. Note that this is only useful during the initial user presence data fetch, as subsequent fetches should use the `last_update_id` parameter, which will act as the limit on how much presence data is returned. `history_limit_days` is ignored if `last_update_id` is passed with a value greater than `0`, indicating that the client already has some presence data. Changes: New in Zulip 10.0 (feature level 288).
`new_user_input`	Boolean	No	Whether the user has interacted with the client (e.g. moved the mouse, used the keyboard, etc.) since the previous presence request from this client. The server uses data from this parameter to implement certain usage statistics. User interface clients that might run in the background, without the user ever interacting with them, should be careful to only pass `true` if the user has actually interacted with the client in order to avoid corrupting usage statistics graphs. Default value: false
`last_update_id`	Integer	No	The identifier that specifies what presence data the client already has received, which allows the server to only return more recent user presence data. This should be set to `-1` during initialization of the client in order to fetch all user presence data, unless the client is obtaining initial user presence metadata from the `POST /register` endpoint. In subsequent queries to this endpoint, this value should be set to the most recent value of `presence_last_update_id` returned by the server in this endpoint's response, which implements incremental fetching of user presence data. When this parameter is passed, the user presence data in the response will always be in the modern format. Changes: New in Zulip 9.0 (feature level 263). Previously, the server sent user presence data for all users who had been active in the last two weeks unconditionally.
`status`	String	Yes	The status of the user on this client. Clients should report the user as `"active"` on this device if the client knows that the user is presently using the device (and thus would potentially see a notification immediately), even if the user has not directly interacted with the Zulip client. Otherwise, it should report the user as `"idle"`. See the related `new_user_input` parameter for how a client should report whether the user is actively using the Zulip client. Valid values: `"active"` `"idle"`
`slim_presence`	Boolean	No	Legacy parameter for configuring the format (modern or legacy) in which the server will return user presence data for the organization. Modern clients should use `last_update_id`, which guarantees that user presence data will be returned in the modern format, and should not pass this parameter as `true` unless interacting with an older server. Legacy clients that do not yet support `last_update_id` may use the value of `true` to request the modern format for user presence data. Note: The legacy format for user presence data will be removed entirely in a future release. Changes: Deprecated in Zulip 9.0 (feature level 263). Using the modern `last_update_id` parameter is the recommended way to request the modern format for user presence data. New in Zulip 3.0 (no feature level as it was an unstable API at that point). Default value: false

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.