Get a user's presence

GET https://gizmo.zulipchat.com/api/v1/users/{user_id_or_email}/presence

Get the presence status for a specific user.

This endpoint is most useful for embedding data about a user's presence status in other sites (e.g. an employee directory). Full Zulip clients like mobile/desktop apps will want to use the main presence endpoint, which returns data for all active users in the organization, instead.

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 for "iago@zulip.com".
result = client.get_user_presence("iago@zulip.com")
print(result)

curl -sSX GET -G https://gizmo.zulipchat.com/api/v1/users/iago@zulip.com/presence \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

Parameters

user_id_or_email string required in path

Example: "iago@zulip.com"

The ID or Zulip API email address of the user whose presence you want to fetch.

Changes: New in Zulip 4.0 (feature level 43). Previous versions only supported identifying the user by Zulip API email.


Response

Return values

  • presence: object

    An object containing the presence details for the user.

    • {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.

      • timestamp: integer

        When this update was received. If the timestamp is more than a few minutes in the past, the user is offline.

      • status: string

        Whether the user had recently interacted with Zulip at the time of the timestamp.

        Will be either "active" or "idle"

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": "",
    "presence": {
        "aggregated": {
            "status": "active",
            "timestamp": 1532697622
        },
        "website": {
            "status": "active",
            "timestamp": 1532697622
        }
    },
    "result": "success"
}