Update your status

POST https://chat.zulip.org/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://chat.zulip.org/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"
}