Update your presence

POST https://chat.django-denmark.org/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://chat.django-denmark.org/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

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
}