Set "typing" status

POST https://pelikan.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: 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",
    "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)

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://pelikan.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]'

Parameters

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