Update your status
POST https://snowdrop.zulipchat.com/api/v1/users/me/status
Change your status.
A request to this endpoint will only change the parameters passed.
For example, passing just status_text
requests a change in the status
text, but will leave the status emoji unchanged.
Clients that wish to set the user's status to a specific value should
pass all supported parameters.
Changes: In Zulip 5.0 (feature level 86), added support for
emoji_name
, emoji_code
, and reaction_type
parameters.
Usage examples
#!/usr/bin/env python3
import zulip
# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")
# The request contains the new status and "away" boolean.
request = {
"status_text": "on vacation",
"away": False,
"emoji_name": "car",
"emoji_code": "1f697",
"reaction_type": "unicode_emoji",
}
result = client.call_endpoint(url="/users/me/status", method="POST", request=request)
print(result)
curl -sSX POST https://snowdrop.zulipchat.com/api/v1/users/me/status \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode 'status_text=on vacation' \
--data-urlencode away=true \
--data-urlencode emoji_name=car \
--data-urlencode emoji_code=1f697 \
--data-urlencode reaction_type=unicode_emoji
Parameters
status_text string optional
Example: "on vacation"
The text content of the status message. Sending the empty string
will clear the user's status.
Note: The limit on the size of the message is 60 characters.
emoji_name string optional
Example: "car"
The name for the emoji to associate with this status.
Changes: New in Zulip 5.0 (feature level 86).
emoji_code string optional
Example: "1f697"
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the reaction_type
.
Changes: New in Zulip 5.0 (feature level 86).
reaction_type string optional
Example: "unicode_emoji"
A string indicating the type of emoji. Each emoji reaction_type
has an independent namespace for values of emoji_code
.
Must be one of the following values:
-
unicode_emoji
: In this namespace, emoji_code
will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
-
realm_emoji
: In this namespace, emoji_code
will be the ID of
the uploaded custom emoji.
-
zulip_extra_emoji
: These are special emoji included with Zulip.
In this namespace, emoji_code
will be the name of the emoji (e.g.
"zulip").
Changes: New in Zulip 5.0 (feature level 86).
away boolean optional Deprecated
Example: true
Whether the user should be marked as "away".
Changes: Deprecated in Zulip 6.0 (feature level 148);
starting with that feature level, away
is a legacy way to
access the user's presence_enabled
setting, with
away = !presence_enabled
. To be removed in a future release.
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 no changes were requested:
{
"code": "BAD_REQUEST",
"msg": "Client did not pass any new values.",
"result": "error"
}
An example JSON error response when the
status_text
message exceeds the limit of
60 characters:
{
"code": "BAD_REQUEST",
"msg": "status_text is too long (limit: 60 characters)",
"result": "error"
}
An example JSON error response when emoji_name
is not specified
but emoji_code
or reaction_type
is specified:
{
"code": "BAD_REQUEST",
"msg": "Client must pass emoji_name if they pass either emoji_code or reaction_type.",
"result": "error"
}
An example JSON error response when the emoji name does not exist:
{
"code": "BAD_REQUEST",
"msg": "Emoji 'invalid' does not exist",
"result": "error"
}
An example JSON error response when the emoji name is invalid:
{
"code": "BAD_REQUEST",
"msg": "Invalid emoji name.",
"result": "error"
}
An example JSON error response when the custom emoji is invalid:
{
"code": "BAD_REQUEST",
"msg": "Invalid custom emoji.",
"result": "error"
}