Set "typing" status

POST https://zulip.cs.ut.ee/api/v1/typing

Notify other users whether the current user is typing a message.

Clients implementing Zulip's typing notifications protocol should work as follows:

  • Send a request to this endpoint with "op": "start" when a user starts typing a message, and also every 10 seconds (TYPING_STARTED_WAIT_PERIOD) that the user continues to actively type or otherwise interact with the compose UI (e.g. interacting with the compose box emoji picker).
  • Send a request to this endpoint with "op": "stop" when a user pauses using the compose UI for at least 5 seconds (TYPING_STOPPED_WAIT_PERIOD) or cancels the compose action (if it had previously sent a "start" operation for that compose action).
  • Start displaying "Sender is typing" for a given conversation when the client receives an "op": "start" event from the GET /events endpoint.
  • Continue displaying "Sender is typing" until they receive an "op": "stop" event from the GET /events endpoint or 15 seconds (TYPING_STARTED_EXPIRY_PERIOD) have passed without a new "op": "start" event for that conversation.
  • Support for displaying stream typing notifications was new in Zulip 4.0 (feature level 58). Clients should indicate they support processing stream typing events via the stream_typing_notifications value in the client_capabilities parameter to POST /register endpoint.

This protocol is designed to allow the server-side typing notifications implementation to be stateless while being resilient; network failures cannot result in a user being incorrectly displayed as perpetually typing.

See the typing notification docs for additional design details on Zulip's typing notifications protocol.

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# The user has started typing in the group direct message
# with Iago and Polonius
user_id1 = 10
user_id2 = 11

request = {
    "op": "start",
    "to": [user_id1, user_id2],
}
result = client.set_typing_status(request)

# The user has finished typing in the group direct message
# with Iago and Polonius
user_id1 = 10
user_id2 = 11

request = {
    "op": "stop",
    "to": [user_id1, user_id2],
}
result = client.set_typing_status(request)

# The user has started to type in topic "typing status"
# of stream "Denmark"
stream_id = client.get_stream_id("Denmark")["stream_id"]
topic = "typing status"

request = {
    "type": "stream",
    "op": "start",
    "to": [stream_id],
    "topic": topic,
}
result = client.set_typing_status(request)

# The user has finished typing in topic "typing status"
# of stream "Denmark"
stream_id = client.get_stream_id("Denmark")["stream_id"]
topic = "typing status"

request = {
    "type": "stream",
    "op": "stop",
    "to": [stream_id],
    "topic": topic,
}
result = client.set_typing_status(request)

print(result)

More examples and documentation can be found here.

const zulipInit = require("zulip-js");

// Pass the path to your zuliprc file here.
const config = { zuliprc: "zuliprc" };

(async () => {
    const client = await zulipInit(config);

    const user_id1 = 9;
    const user_id2 = 10;

    const typingParams = {
        op: "start",
        to: [user_id1, user_id2],
    };

    // The user has started typing in the group direct message
    // with Iago and Polonius
    console.log(await client.typing.send(typingParams));
})();

curl -sSX POST https://zulip.cs.ut.ee/api/v1/typing \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode type=direct \
    --data-urlencode op=start \
    --data-urlencode 'to=[9, 10]'

Parameters

type string optional

Example: "direct"

Type of the message being composed.

Changes: In Zulip 7.0 (feature level 174), "direct" was added as the preferred way to indicate a direct message is being composed, becoming the default value for this parameter and deprecating the original "private".

New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages.

Must be one of: "direct", "stream", "private". Defaults to "direct".


op string required

Example: "start"

Whether the user has started ("start") or stopped ("stop") typing.

Must be one of: "start", "stop".


to (integer)[] required

Example: [9, 10]

For "direct" type it is the user IDs of the recipients of the message being typed. Send a JSON-encoded list of user IDs. (Use a list even if there is only one recipient.)

For "stream" type it is a single element list containing ID of stream in which the message is being typed.

Changes: Support for typing notifications for stream messages is new in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages.

Before Zulip 2.0.0, this parameter accepted only a JSON-encoded list of email addresses. Support for the email address-based format was removed in Zulip 3.0 (feature level 11).


topic string optional

Example: "typing notifications"

Topic to which message is being typed. Required for the "stream" type. Ignored in the case of "direct" type.

Changes: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages.


Response

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": "",
    "result": "success"
}

An example JSON error response for when user sends to multiple streams:

{
    "code": "BAD_REQUEST",
    "msg": "Cannot send to multiple streams",
    "result": "error"
}