Update your status

Change your status.

POST https://z.labs.greyorange.com/api/v1/users/me/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.

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://z.labs.greyorange.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.


away boolean optional

Example: true

Whether the user should be marked as "away".


emoji_name string optional

Example: "car"

The name for the emoji to associate with this status.


emoji_code string optional

Example: "1f697"

A unique identifier, defining the specific emoji codepoint requested, within the namespace of the reaction_type.

For example, for unicode_emoji, this will be an encoding of the Unicode codepoint; for realm_emoji, it'll be the ID of the realm emoji.


reaction_type string optional

Example: "unicode_emoji"

One of the following values:

  • unicode_emoji: Unicode emoji (emoji_code will be its Unicode codepoint).
  • realm_emoji: Custom emoji. (emoji_code will be its ID).
  • zulip_extra_emoji: Special emoji included with Zulip. Exists to namespace the zulip emoji.

Response

Example response

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"
}