Update your presence

POST https://colasvigilanza.chat.ciclat.ra.it/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://colasvigilanza.chat.ciclat.ra.it/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

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.


new_user_input boolean optional

Example: false

Whether the user has interacted with the client (e.g. moved the mouse, used the keyboard, etc.) since the previous presence request from this client.

The server uses data from this parameter to implement certain usage statistics.

User interface clients that might run in the background, without the user ever interacting with them, should be careful to only pass true if the user has actually interacted with the client in order to avoid corrupting usage statistics graphs.

Defaults to false.


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.

    • Will be one of these two formats (modern or legacy) for user presence data:

      • {user_id}: object

        Presence data (modern format) for the user with the specified ID.

        • active_timestamp: integer

          The UNIX timestamp of the last time a client connected to Zulip reported that the user was actually present (e.g. via focusing a browser window or interacting with a computer running the desktop app).

          Clients should display users with a current active_timestamp as fully present.

        • idle_timestamp: integer

          The UNIX timestamp of the last time the user had a client connected to Zulip, including idle clients where the user hasn't interacted with the system recently.

          The Zulip server has no way of distinguishing whether an idle web app user is at their computer, but hasn't interacted with the Zulip tab recently, or simply left their desktop computer on when they left.

          Thus, clients should display users with a current idle_timestamp but no current active_timestamp as potentially present.

      • {user_email}: object

        Presence data (legacy format) for the user with the specified Zulip API email.

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

          • client: string

            The client's platform name.

            Changes: Starting with Zulip 7.0 (feature level 178), this will always be "website" as the server no longer stores which client submitted presence data.

          • status: string

            The status of the user on this client. Will be either "idle" or "active".

          • timestamp: integer

            The UNIX timestamp of when this client sent the user's presence to the server with the precision of a second.

          • pushable: boolean

            Whether the client is capable of showing mobile/push notifications to the user.

            Not present in objects with the "aggregated" key.

            Changes: Starting with Zulip 7.0 (feature level 178), always false when present as the server no longer stores which client submitted presence data.

  • zephyr_mirror_active: boolean

    Legacy property for a part of the Zephyr mirroring system.

    Deprecated. Clients should ignore this field.

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
}