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
Python
JavaScript
curl
#!/usr/bin/env python3importzulip# 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 Poloniususer_id1=10user_id2=11request={"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 Poloniususer_id1=10user_id2=11request={"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.
constzulipInit=require("zulip-js");// Pass the path to your zuliprc file here.constconfig={zuliprc:"zuliprc"};(async()=>{constclient=awaitzulipInit(config);constuser_id1=9;constuser_id2=10;consttypingParams={op:"start",to:[user_id1,user_id2],};// The user has started typing in the group direct message// with Iago and Poloniusconsole.log(awaitclient.typing.send(typingParams));})();
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".
opstringrequired
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_idintegeroptional
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.
topicstringoptional
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"}