Set "typing" status

POST https://recurse.zulipchat.com/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 composing a message.
  • While the user continues to actively type or otherwise interact with the compose UI (e.g. interacting with the compose box emoji picker), send regular "op": "start" requests to this endpoint, using server_typing_started_wait_period_milliseconds in the POST /register response as the time interval between each request.
  • Send a request to this endpoint with "op": "stop" when a user has stopped using the compose UI for the time period indicated by server_typing_stopped_wait_period_milliseconds in the POST /register response or when a user cancels the compose action (if it had previously sent a "start" notification for that compose action).
  • Start displaying a visual typing indicator for a given conversation when a typing op:start event is received from the server.
  • Continue displaying a visual typing indicator for the conversation until a typing op:stop event is received from the server or the time period indicated by server_typing_started_expiry_period_milliseconds in the POST /register response has passed without a new typing "op": "start" event for the conversation.

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

See the subsystems documentation on typing indicators for additional design details on Zulip's typing notifications protocol.

Changes: Clients shouldn't care about the APIs prior to Zulip 8.0 (feature level 215) for stream typing notifications, as no client actually implemented the previous API for those.

Support for displaying stream typing notifications was new in Zulip 4.0 (feature level 58). Clients should indicate they support processing stream typing notifications via the stream_typing_notifications value in the client_capabilities parameter of the POST /register endpoint.

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",
    "stream_id": 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",
    "stream_id": 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://recurse.zulipchat.com/api/v1/typing \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode type=direct \
    --data-urlencode op=start \
    --data-urlencode 'to=[9, 10]' \
    --data-urlencode stream_id=7

Parameters

type string optional

Example: "direct"

Type of the message being composed.

Changes: In Zulip 8.0 (feature level 215), stopped supporting "private" as a valid value for this parameter.

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". 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)[] optional

Example: [9, 10]

User IDs of the recipients of the message being typed. Required for the "direct" type. Ignored in the case of "stream" type. Send a JSON-encoded list of user IDs. (Use a list even if there is only one recipient.)

Changes: In Zulip 8.0 (feature level 215), stopped using this parameter for the "stream" type. Previously, in the case of the "stream" type, it accepted a single-element list containing the ID of the stream. A new parameter, stream_id, is now used for this.

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).


stream_id integer optional

Example: 7

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

Changes: New in Zulip 8.0 (feature level 215). Previously, a single-element list containing the ID of the stream was passed in to parameter.


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"
}