Get a user's presence
GET https://eiot.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.
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)
The -u line implements HTTP Basic authentication.
See the Authorization header documentation for how
to get those credentials for Zulip users and bots.
curl -sSX GET -G https://eiot.zulipchat.com/api/v1/users/iago@zulip.com/presence \
-u EMAIL_ADDRESS: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
-
server_timestamp: number
The time when the server fetched the presence data
included in the response. Matches the similar field
in other presence responses.
Changes: New in Zulip 12.0 (feature level 497).
-
presence: object
An object containing the presence details for the user.
The object contains both the modern format fields
(active_timestamp and idle_timestamp) and the legacy
format fields (website and aggregated dictionaries,
which contain a timestamp and a status string). New
integrations should use the modern fields; the legacy
fields are retained for backwards compatibility.
Changes: In Zulip 12.0 (feature level 497),
the website and aggregated legacy dictionaries were
restored alongside the modern fields, for backwards
compatibility with integrations written against earlier
versions of the API.
In Zulip 12.0 (feature level 487), the active_timestamp
and idle_timestamp fields were added to this object, and
the website and aggregated dictionaries were
temporarily removed.
-
active_timestamp: integer
The UNIX timestamp of the last time a client connected
to Zulip reported that the user was actually present.
-
idle_timestamp: integer
The UNIX timestamp of the last time the user had a
client connected to Zulip, including idle clients.
-
website: object
Presence details for the user in the legacy format.
Starting with Zulip 7.0 (feature level 178), the
website and aggregated dictionaries always contain
identical data, since the server no longer stores which
client submitted presence updates.
-
aggregated: object
Presence details for the user in the legacy format.
Unlike website, the status will be "offline" if
the most recent presence update is older than the
server's offline threshold.
-
status: string
The status of the user. Will be either "idle",
"active", or "offline".
-
timestamp: integer
The UNIX timestamp of when the user's presence data
was last updated.
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": {
"active_timestamp": 1656958520,
"aggregated": {
"status": "active",
"timestamp": 1656958520
},
"idle_timestamp": 1656958530,
"website": {
"status": "active",
"timestamp": 1656958520
}
},
"result": "success",
"server_timestamp": 1656958540.123
}