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)
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]'
Parameters
type string optional
Example: "direct"
Type of the message being composed.
Changes: 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"
, "private"
.
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)[] required
Example: [9, 10]
For "direct"
type it is the user IDs of the recipients of the message
being typed. Send a JSON-encoded list of user IDs. (Use a list even if
there is only one recipient.)
For "stream"
type it is a single element list containing ID of stream in
which the message is being typed.
Changes: 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).
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"
}