Get user 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.

GET https://z.labs.greyorange.com/api/v1/users/{user_id_or_email}/presence

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://z.labs.greyorange.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 user_id or Zulip display 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 display email.


Response

Return values

  • presence: object

    An object containing the presence details for every client the user has logged into.

    • {client_name} or aggregated: object

      the keys for these objects are the names of the different clients where this user is logged in, like website, ZulipDesktop, ZulipTerminal, or ZulipMobile. There is also an aggregated key, which matches the contents of the object that has been updated most recently. For most applications, you'll just want to look at the aggregated key.

      • 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

        either active or idle: whether the user had recently interacted with Zulip at the time in the timestamp (this distinguishes orange vs. green dots in the Zulip web UI; orange/idle means we don't know whether the user is actually at their computer or just left the Zulip app open on their desktop).

Example response

A typical successful JSON response may look like:

{
    "msg": "",
    "presence": {
        "ZulipMobile": {
            "status": "active",
            "timestamp": 1522687421
        },
        "aggregated": {
            "status": "active",
            "timestamp": 1532697622
        },
        "website": {
            "status": "active",
            "timestamp": 1532697622
        }
    },
    "result": "success"
}