zulip/docs/subsystems/typing-indicators.md

Typing indicators

Zulip supports a feature called "typing indicators."

Typing indicators are status messages (or visual indicators) that tell you when another user is writing a message to you. Zulip's typing UI is similar to what you see in other chat/text systems.

This document describes how we have implemented the feature in the Zulip web app, and our main audience is developers who want to understand the system and possibly improve it. Any client should be able follow the protocol documented here.

Typing indicators are implemented for both direct message conversations and channel conversations in the web app.

There are two major roles for users in this system:

• The "writing user" is composing a message.
• The "receiving user" is waiting to receive a message (or possibly ready to shift their attention elsewhere).

Any Zulip user can play either one of these roles, and sometimes they can be playing both roles at once. Having said that, you can generally understand the system in terms of a single message being composed by the "writing user."

On a high level the typing indicators system works like this:

• The client for the "writing user" sends requests to the server.
• The server broadcasts events to other users.
• The clients for "receiving users" receive events and conditionally show typing indicators, depending on where the clients are narrowed.

Privacy settings

Note that there is a user-level privacy setting to disable sending typing notifications that a client should check when implementing the "writing user" protocol below. See send_private_typing_notifications in the UserBaseSettings model in zerver/models/users.py and in the user_settings object in the POST /register response.

Writing user

When a "writing user" starts to compose a message, the client sends a request to POST /typing with an op of start and a list of potential message recipients. The web app function that facilitates this is called send_typing_notification_ajax.

If the "writing user" is composing a long message, we want to send repeated updates to the server so that downstream clients know the user is still typing. Zulip messages tend to be longer than messages in other chat/text clients, so this detail is important.

We have a small state machine in web/shared/src/typing_status.ts that makes sure subsequent "start" requests get sent out. The frequency of these requests is determined by server_typing_started_wait_period_milliseconds in the POST /register response.

If the "writing user" goes for a while without any text input, then we send a request to POST /typing with an op of stop. The time period a client should wait before sending the request is determined by server_typing_stopped_wait_period_milliseconds in the POST /register response. We also immediately send "stop" notification when the user explicitly aborts composing a message by closing the compose box (or other actions).

A common scenario is that a user is just pausing to think for a few seconds, but they still intend to finish the message. Of course, that's hard to distinguish from the scenario of the user got pulled away from their desk. For the former case, where the "writing user" completes the message with lots of pauses for thinking, a series of "start" and "stop" messages may be sent over time. Timeout values reflect tradeoffs, where we have to guess how quickly people type, how long they pause to think, and how frequently they get interrupted.

Server

The server piece of typing notifications is currently pretty straightforward, since we take advantage of Zulip's events system.

We deliberately designed the server piece to be stateless, which minimizes the possibility of backend bugs and gives clients more control over the user experience.

As such, the server piece here is basically a single Django view function with a small bit of library support to send out events to clients.

Requests come in to send_notification_backend, which is in zerver/views/typing.py. For direct message typing notifications, the call to check_send_typing_notification does the heavy lifting.

One of the main things that the server does is to validate that the user IDs in the to parameter are for valid, active users in the realm.

Once the request has been validated, the server sends events to potential recipients of the message. The event type for that payload is typing. See the function do_send_typing_notification in zerver/actions/typing.py for more details.

For channel typing notifications, the server also handles the logic for determining which users should receive the typing events based on channel subscribers.

Receiving user

When a user plays the role of a "receiving user," the client handles incoming "typing" events from the server, and the client will display a typing indicator only when both of these conditions are true:

• The "writing user" is still likely typing.
• The "receiving user" is in a view where they'd see the eventual message.

The client code starts by processing events, and it maintains data structures, and then it eventually shows or hides status messages.

We'll describe the flow of data through the web app as a concrete example.

The events will come in to web/src/server_events_dispatch.js. The stop and start operations get further handled by web/src/typing_events.ts.

The main goal is then to triage which events should lead to display changes.

The web app client maintains a list of incoming "typists" using code in web/src/typing_data.ts. The API here has functions like the following:

• add_typist
• remove_typist
• get_group_typists
• get_all_direct_message_typists

One subtle thing that the client has to do here is to maintain timers for typing notifications. The value of server_typing_started_expiry_period_milliseconds in the POST /register response is used to determine when the "writing user" has abandoned the message. Of course, the "writing user" will also explicitly send us stop notifications at certain times.

When it finally comes to displaying the notification, the web app eventually calls render_notifications_for_narrow.

Ecosystem

Even though the server is stateless, any developer working on a client needs to be mindful of timing/network considerations that affect the overall system.

In general, client developers should agree on timeout parameters for how frequently we "kickstart" typing notifications for users sending long messages. This means standardizing the "writing user" piece of the system. It's possible that certain clients will have slightly different mechanisms for detecting that users have abandoned messages, but the re-transmit frequency should be similar.

When implementing the "receiving user" piece, it's important to realize how clients behave on the other end of the protocol. It's possible, for example, to never receive a "stop" notification from a client that was shut down abruptly. You should allow reasonable amounts of time for the other side to send notifications, allowing for network delays and server delays, but you should not let the notifications become too "sticky" either.

Roadmap

An area for refinement is to tune the timing values a bit. Right now, we are possibly too aggressive about sending stop messages when users are just pausing to think. It's possible to better account for typing speed or other heuristic things like how much of the message has already been typed.