Set "typing" status

POST https://citeca.han-solo.net/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 channel typing notifications, as no client actually implemented the previous API for those.

Support for displaying channel typing notifications was new in Zulip 4.0 (feature level 58). Clients should indicate they support processing channel 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 two users, "user_a" and "user_b".
request = {
    "op": "start",
    "to": [user_a_id, user_b_id],
}
result = client.set_typing_status(request)
# The user has finished typing in the group direct message
# with "user_a" and "user_b".
request = {
    "op": "stop",
    "to": [user_a_id, user_b_id],
}
result = client.set_typing_status(request)
# The user has started typing in a topic/channel.
request = {
    "type": "stream",
    "op": "start",
    "stream_id": stream_id,
    "topic": topic,
}
result = client.set_typing_status(request)
# The user has finished typing in a topic/channel.
request = {
    "type": "stream",
    "op": "stop",
    "stream_id": 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://citeca.han-solo.net/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

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 when the user composes a channel message and stream_id is not specified:

{
    "code": "BAD_REQUEST",
    "msg": "Missing channel ID",
    "result": "error"
}