Zulip homepage

API documentation home

Integrations

Interactive bots (beta)

REST API

Messages

Drafts

Streams

Users

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

Add an emoji reaction

Add an emoji reaction to a message.

POST https://zulip.schiffrin-zulip.cloud.edu.au/api/v1/messages/{message_id}/reactions

Usage examples

  • Python
  • curl

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Add an emoji reaction
request = {
    "message_id": message_id,
    "emoji_name": "octopus",
}

result = client.add_reaction(request)
print(result)


curl -sSX POST https://zulip.schiffrin-zulip.cloud.edu.au/api/v1/messages/43/reactions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode emoji_name=octopus

Parameters

message_id integer required in path

Example: 43

The target message's ID.

emoji_name string required

Example: "octopus"

The target emoji's human-readable name.

To find an emoji's name, hover over a message to reveal three icons on the right, then click the smiley face icon. Images of available reaction emojis appear. Hover over the emoji you want, and note that emoji's text name.

emoji_code string optional

Example: "1f419"

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

For most API clients, you won't need this, but it's important for Zulip apps to handle rare corner cases when adding/removing votes on an emoji reaction added previously by another user.

If the existing reaction was added when the Zulip server was using a previous version of the emoji data mapping between Unicode codepoints and human-readable names, sending the emoji_code in the data for the original reaction allows the Zulip server to correctly interpret your upvote as an upvote rather than a reaction with a "different" emoji.

reaction_type string optional

Example: "unicode_emoji"

If an app is adding/removing a vote on an existing reaction, it should pass this parameter using the value the server provided for the existing reaction for specificity. Supported 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.

Changes: In Zulip 3.0 (feature level 2), this become optional for custom emoji; previously, this endpoint assumed unicode_emoji if this parameter was not specified.

Response

Example response

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success"
}

An example JSON error response for when the emoji code is invalid:

{
    "code": "BAD_REQUEST",
    "msg": "Invalid emoji code",
    "result": "error"
}