Get presence of all users

GET https://agaric.zulipchat.com/api/v1/realm/presence

Get the presence information of all the users in an organization.

If the CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE server-level setting is set to true, presence information of only accessible users are returned.

See Zulip's developer documentation for details on the data model for presence in Zulip.

Usage examples

#!/usr/bin/env python3

import zulip

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

# Get presence information of all the users in an organization.
result = client.get_realm_presence()
print(result)

curl -sSX GET -G https://agaric.zulipchat.com/api/v1/realm/presence \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

Parameters

This endpoint does not accept any parameters.

Response

Return values

• server_timestamp: number

  The time when the server fetched the presences data included in the response.

• presences: object

  A dictionary where each entry describes the presence details of a user in the Zulip organization.

  • {user_email}: object

    Object containing the details of a user's presence. The object's key is the user's Zulip API email.

    • {client_name} or "aggregated": object

      Object containing the details of the user's presence.

      Changes: Starting with Zulip 7.0 (feature level 178), this will always contain two keys, "website" and "aggregated", with identical data. The server no longer stores which client submitted presence updates.

      Previously, the {client_name} keys for these objects were the names of the different clients where the user was logged in, for example website or ZulipDesktop.

      • client: string

        The client's platform name.

        Changes: Starting with Zulip 7.0 (feature level 178), this will always be "website" as the server no longer stores which client submitted presence data.

      • status: string

        The status of the user on this client. Will be either "idle" or "active".

      • timestamp: integer

        The UNIX timestamp of when this client sent the user's presence to the server with the precision of a second.

      • pushable: boolean

        Whether the client is capable of showing mobile/push notifications to the user.

        Not present in objects with the "aggregated" key.

        Changes: Starting with Zulip 7.0 (feature level 178), always false when present as the server no longer stores which client submitted presence data.

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "msg": "",
    "presences": {
        "iago@zulip.com": {
            "aggregated": {
                "client": "website",
                "status": "active",
                "timestamp": 1656958485
            },
            "website": {
                "client": "website",
                "pushable": false,
                "status": "active",
                "timestamp": 1656958485
            }
        }
    },
    "result": "success",
    "server_timestamp": 1656958539.6287155
}