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: 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)
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://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]' \
--data-urlencode stream_id=7
Parameters
type string optional
Example: "direct"
Type of the message being composed.
Changes: In Zulip 9.0 (feature level 248), "channel" was added as
an additional value for this parameter to indicate a channel message is
being composed.
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", "channel".
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" or "channel" type.
Clients should send a JSON-encoded list of user IDs, 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 channel. A new parameter,
stream_id, is now used for this. Note that the "channel" type did not
exist at this feature level.
Support for typing notifications for channel' 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 channel in which the message is being typed. Required for the "stream"
or "channel" 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 channel was passed in to parameter.
topic string optional
Example: "typing notifications"
Topic to which message is being typed. Required for the "stream" or "channel"
type. Ignored in the case of "direct" type.
Note: When "(no topic)" or the value of realm_empty_topic_display_name
found in the POST /register response is used for this
parameter, it is interpreted as an empty string.
Changes: Before Zulip 10.0 (feature level 372),
"(no topic)" was not interpreted as an empty string.
Before Zulip 10.0 (feature level 334), empty string
was not a valid topic name for channel messages.
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 when the user composes a channel message
and stream_id is not specified:
{
"code": "BAD_REQUEST",
"msg": "Missing channel ID",
"result": "error"
}