# React message

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

- Endpoint: `POST https://api.returning.ai/v1/messages/react`
- Section: Community / Messaging
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `replyMessage` (Shown in the dashboard as "Reply Message")
- Retries: Repeating the same reaction adds nothing
- Guide: hand-written
- Verified: code, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/messaging/react-message

## 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.

**Instead:** Use [Reply message](https://docs.returning.ai/api-reference/messaging/reply-message.md) instead when the trader needs a written answer.

**Can't be undone here:** There is no API call to remove a reaction. It stays on the message until someone removes it in the community.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `replyMessage`

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `replyMessage`. There is no separate reaction permission. (`Bearer <API_KEY>`) |
| `Content-Type` | `string` | Yes | Request body format. (`application/json`) |

### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `messageId` | `string` | Yes | The message to react to, from `data.messages.id` in Get Messages. It must be in your community. (Message ID) |
| `sender` | `string` | Yes | 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. (Username or email of a member) |
| `emoji` | `string` | Yes | 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. (Emoji short name) |

### Example request

```bash
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`.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `status` | `string` | always | Result of the request. (`success`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |

### Example response (200)

```json
{
  "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 request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | `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. |
| 401 | - | 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. |
| 403 | - | 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 data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | - | `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 backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | 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](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry.

## Next step

- [Get messages](https://docs.returning.ai/api-reference/messaging/get-messages.md): `GET /v1/messages`. Read the channel again to find the next message to handle.
- [Answer in writing with Reply message](https://docs.returning.ai/api-reference/messaging/reply-message.md): `POST /v1/messages/reply`.