Returning.AIDocs
v1

API reference / Messaging

.md

React message

Add an emoji reaction to one message in your community, as an existing member.

Last updated 28 Oct 2026API v1

Method
POST
Path
https://api.returning.ai/v1/messages/react
Permission
replyMessage
Retries
Repeating the same reaction adds nothing

When to use this

  • Your support account acknowledges a trader's message with a reaction instead of a reply.
  • Your system marks messages it has handled, so your team can see them in the channel.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
replyMessageShown in the dashboard as “Reply Message”

Use a Community API key with replyMessage; reactions share the reply permission. Keep the key on your server. The key decides the community, so you can only react to messages in that community and never send a community ID. A personal user API key with its own reaction permission also works; then the reaction is posted as the key's owner.

Behaviour#

The reaction shows on the message straight away, under the sender's name. The sender must be able to see the channel, even with a Community API key. Your community's reaction webhooks fire for channel messages, and a reaction in a direct conversation lets the other person know.

Sending the same emoji for the same message and sender again doesn't add a second reaction. Messages in a forum topic accept only :thumbsup:.

Request#

Headers#

Authorization#stringREQUIRED
Community API key with replyMessage. There is no separate reaction permission.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

messageId#stringREQUIRED
The message to react to, from data.messages.id in Get Messages. It must be in your community.

RuleMessage ID

Eg"66f000000000000000000a21"

sender#stringREQUIRED
The member who reacts, by username or email. Required with a Community API key. With a personal user API key, leave it out to react as the key's owner.

RuleUsername or email of a member

Eg"support@example.com"

emoji#stringREQUIRED
The emoji's short name with colons, such as :thumbsup: or :fire:. Your community's custom emoji work by their short name too. An emoji character itself is rejected.

RuleEmoji short name

Eg":thumbsup:"

curl --request POST \
  --url https://api.returning.ai/v1/messages/react \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messageId": "66f000000000000000000a21",
    "sender": "support@example.com",
    "emoji": ":thumbsup:"
  }'

Response#

A 200 means the reaction was added. The response carries only status and message.

status#stringALWAYS
Result of the request.

Rulesuccess

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Message reacted successfully"

{
  "status": "success",
  "message": "Message reacted successfully"
}

Errors#

Validation errors use meta, message, detail and solution, with detail naming the field. Every other error has message, sometimes with status or detail. None has a machine-readable code, so branch on the HTTP status and read message.

Fix the request03

400Fix the request
message says which: Message React Payload Validation validation error. (a field is missing or malformed; detail names it), Emoji not found (use a short name such as :thumbsup:), Sender field is required (a Community API key needs sender), or Forum message cannot be reacted with this emoji (forum topics accept only :thumbsup:). Nothing changed.
401Fix the request
The key is missing (Invalid token), unknown (Invalid API key) or expired, or it lacks replyMessage (Your API key does not have permission to access this action). Add the permission in Settings > Integration > API Keys.
403Fix the request
The sender can't react in this channel. They can't see it, they are a guest, or the channel is a preview channel. Pick a sender who can see the channel. Nothing changed.

Fix the data01

404Fix the data
message says which: Message not found (the ID isn't a message in your community), User not found (no member has that sender) or Channel not found. Nothing changed.

Retry with backoff01

500Retry with backoff
The reaction failed, or the key could not be checked (Authentication failed). Retrying the same reaction is safe.

Retries

Repeating the same reaction doesn't add a second one, so a retry after a timeout or a 500 is safe. It can fire your reaction webhooks again. Over the rate limit, requests return 429; wait for the window to reset, then retry.

{
  "status": "error",
  "message": "Emoji not found"
}

Next step#

Get messagesGET/v1/messagesRead the channel again to find the next message to handle.