Update your presence
POST https://scala.zulipchat.com/api/v1/users/me/presence
Update the current user's presence and fetch presence data
of other users in the organization.
This endpoint is meant to be used by clients for both:
-
Reporting the current user's presence status ("active" or "idle")
to the server.
-
Obtaining the presence data of all other users in the organization via
regular polling (in parallel with receiving
presence events).
Accurate user presence is one of the most expensive parts of any
chat application (in terms of bandwidth and other resources). Therefore,
it is important that clients implementing Zulip's user presence system
use the modern last_update_id protocol to
minimize fetching duplicate user presence data.
See Zulip's developer documentation for details
on the data model for user presence in Zulip.
The Zulip server is responsible for implementing invisible mode,
which disables sharing a user's 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 their presence information.
Changes: As of Zulip 8.0 (feature level 228), if the
CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE server-level setting is
true, then user presence data in the response is limited to users
the current user can see/access.
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://scala.zulipchat.com/api/v1/users/me/presence \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode last_update_id=5 \
--data-urlencode history_limit_days=365 \
--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
The identifier that specifies what presence data the client already
has received, which allows the server to only return more recent
user presence data.
This should be set to -1 during initialization of the client in
order to fetch all user presence data, unless the client is obtaining
initial user presence metadata from the
POST /register endpoint.
In subsequent queries to this endpoint, this value should be set to the
most recent value of presence_last_update_id returned by the server
in this endpoint's response, which implements incremental fetching
of user presence data.
When this parameter is passed, the user presence data in the response
will always be in the modern format.
Changes: New in Zulip 9.0 (feature level 263). Previously, the
server sent user presence data for all users who had been active in the
last two weeks unconditionally.
history_limit_days integer optional
Example: 365
Limits how far back in time to fetch user presence data. If not specified,
defaults to 14 days. A value of N means that the oldest presence data
fetched will be from at most N days ago.
Note that this is only useful during the initial user presence data fetch,
as subsequent fetches should use the last_update_id parameter, which
will act as the limit on how much presence data is returned. history_limit_days
is ignored if last_update_id is passed with a value greater than 0,
indicating that the client already has some presence data.
Changes: New in Zulip 10.0 (feature level 288).
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 on the server.
Otherwise, also requests the server return user presence data for all
users in the organization, which is further specified by the
last_update_id parameter.
Defaults to false.
status string required
Example: "active"
The status of the user on this client.
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 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 (modern or legacy) in
which the server will return user presence data for the organization.
Modern clients should use
last_update_id, which guarantees that
user presence data will be returned in the modern format, and
should not pass this parameter as true 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 for user presence data.
Note: The legacy format for user presence data will be removed
entirely in a future release.
Changes: Deprecated in Zulip 9.0 (feature level 263). Using
the modern last_update_id parameter is the recommended way to
request the modern format for user presence data.
New in Zulip 3.0 (no feature level as it was an unstable API at that
point).
Defaults to false.
Response
Return values
-
presence_last_update_id: integer
The identifier for the latest user presence data returned in
the presences data of the response.
If a value was passed for last_update_id, then this is
guaranteed to be equal to or greater than that value. If it
is the same value, then that indicates to the client that
there were no updates to previously received user presence
data.
The client should then pass this value as the last_update_id
parameter when it next queries this endpoint, in order to only
receive new user presence data and avoid redundantly fetching
already known information.
This will be -1 if no value was passed for
last_update_id and no user
presence data was returned by the server. This can happen, for
example, if an organization has disabled presence.
Changes: New in Zulip 9.0 (feature level 263).
-
server_timestamp: number
Only present if ping_only is false.
The time when the server fetched the presences data included
in the response.
-
presences: object
Only present if ping_only is false.
A dictionary where each entry describes the presence details
of a user in the Zulip organization. Entries can be in either
the modern presence format or the legacy presence format.
These entries will be the modern presence format when the
last_updated_id parameter is passed, or when the deprecated
slim_presence parameter is true.
If the deprecated slim_presence parameter is false and the
last_updated_id parameter is omitted, the entries will be in
the legacy presence API format.
Note: The legacy presence format should only be used when
interacting with old servers. It will be removed as soon as
doing so is practical.
-
zephyr_mirror_active: boolean
Legacy property for a part of the Zephyr mirroring system.
Deprecated. Clients should ignore this field.
Example response(s)
Modern presence format:
{
"msg": "",
"presence_last_update_id": 1000,
"presences": {
"10": {
"active_timestamp": 1656958520,
"idle_timestamp": 1656958530
}
},
"result": "success",
"server_timestamp": 1656958539.6287155
}
Legacy presence format:
{
"msg": "",
"presence_last_update_id": 1000,
"presences": {
"user@example.com": {
"aggregated": {
"client": "website",
"status": "idle",
"timestamp": 1594825445
},
"website": {
"client": "website",
"pushable": false,
"status": "idle",
"timestamp": 1594825445
}
}
},
"result": "success",
"server_timestamp": 1656958539.6287155
}