Update your presence status and fetch presence data for the realm
POST https://xi.zulipchat.com/api/v1/users/me/presence
Update your
presence/availability
status and fetch presence of other users in realm in a bulk.
This is the endpoint meant to be used by clients for both reporting
their presence status to the server and obtaining the presence info
of all other users to build the buddy list by polling it regularly,
in parallel with receiving presence update events via the event system.
Accurate presence is one of the most expensive parts of any team chat application
(in terms of bandwidth and other resources). It's thus important that clients
implementing Zulip's presence system use the modern last_update_id protocol to
minimize fetching duplicate presence data.
If the CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE server-level
setting is set to true, presence information of only accessible
users is included in the response.
See Zulip's developer documentation
for details on the data model for presence in Zulip.
The Zulip server is responsible for implementing invisible
mode, which
disables sharing 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 presence information.
Usage examples
#!/usr/bin/env python3
import zulip
# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")
# Update your presence.
request = {
"status": "active",
"ping_only": False,
"new_user_input": False,
"last_update_id": -1,
}
result = client.update_presence(request)
print(result)
curl -sSX POST https://xi.zulipchat.com/api/v1/users/me/presence \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode last_update_id=5 \
--data-urlencode new_user_input=false \
--data-urlencode ping_only=false \
--data-urlencode slim_presence=false \
--data-urlencode status=active
Parameters
last_update_id integer optional
Example: 5
Specifies what presence data the client already has, allowing the
server to only return presence data more recent than that.
This parameter should be set to -1 during initialization of the
client in order to fetch all data, unless the client is obtaining
initial presence metadata from the POST /register endpoint.
Afterwards, its value should be obtained by reading
presence_last_update_id from the server's response to the previous
request in order to implement incremental fetches of presence data.
Changes: New in Zulip 9.0 (feature level 263). Previously, the
server sent data for all users who had been active in the last two
weeks unconditionally.
ping_only boolean optional
Example: false
Whether the client is sending a ping-only request, meaning it only
wants to update the user's presence status.
Otherwise, also requests the server to return presence data of all
users in the realm, further affected by the last_update_id
parameter.
Defaults to false.
status string required
Example: "active"
The status of the user on this client. Will be either "idle"
or "active".
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 desktop 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.
Must be one of: "idle", "active".
slim_presence boolean optional Deprecated
Example: false
Legacy parameter for configuring the format in which the server will
return presence data for the realm. Modern clients should pass
last_update_id, which implies the client expects the modern format,
and should not pass this property 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. The legacy format, sent
when slim_presence is false, will be removed entirely in a future
release.
Changes: Deprecated in Zulip 9.0 (feature level 263);
using the modern last_update_id API is the recommended way to
request the modern format.
New in Zulip 3.0 (Unstable with no feature level yet).
Defaults to false.
Response
Return values
-
presence_last_update_id: integer
Provides the last_update_id value of the latest presence data
fetched by the server and included in the response in
presences. This allows the client to have an identifier number
up to which it knows it has obtained all the presence data.
The client should then pass this value when it next queries this
endpoint, in order to only receive newer presence data to avoid
redundant fetching of already known information.
Changes: New in Zulip 9.0 (feature level 263).
-
server_timestamp: number
The time when the server fetched the presences data included
in the response.
Only present if ping_only is false.
-
zephyr_mirror_active: boolean
Legacy property for a part of the Zephyr mirroring system.
Deprecated. Clients should ignore this field.
-
presences: object
A dictionary where each entry describes the presence details
of a user in the Zulip organization.
Only present if ping_only is false.
-
A map from {user_id} (modern) or {user_email} (legacy)
properties to objects containing the presence data for that
user.
Depending on the value of slim_presence, the object's key is
either the user's ID or the user's Zulip API email. If
slim_presence is true, the presence information is fetched
in the modern API format which includes active_timestamp and
idle_timestamp of the user.
Note: The old legacy format should only be used when
interacting with old servers. It will be removed as soon as
doing so is practical.
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_last_update_id": 1000,
"presences": {
"10": {
"active_timestamp": 1656958520,
"idle_timestamp": 1656958530
}
},
"result": "success",
"server_timestamp": 1656958539.6287155
}