React Message
POST
/v1/messages/react
What this endpoint does
Authorization: Bearer <communityApiKey>. Keep the key server-side. A browser session token is not a Community API key. Current Community-key permission: replyMessage.Quick start
incomingMessage.id from GET /v1/messages into messageId; use a registered emoji shortname and the configured agent identity in sender.Authentication and permission
Authorization: Bearer <communityApiKey> server-side. Current Community-key permission: replyMessage. With a Community API key, sender is required.Complete examples
GET /v1/messages, copy the target item's id to messageId, and use the configured agent user's email or exact platform username as sender.{
"messageId": "<incomingMessage.id>",
"emoji": ":eyes:",
"sender": "community-agent@example.com"
}messageId is the target; sender is the actor. Do not use the incoming author's numeric user_id or display name as sender. Emoji must be a registered shortname such as :eyes: or :smile:. Raw Unicode such as 👀 returns 400 Emoji not found.Success and readback
/v1/messages does not expose reactions. Verify in the UI or another reaction-capable surface before retrying an ambiguous result. Reaction retry behavior is not documented as an idempotent public contract.Errors and recovery
| Status/message | Recovery |
|---|---|
400 Sender field is required | Set the configured agent user's email or exact username. |
400 Emoji not found | Use a registered shortname, not raw Unicode. |
404 User not found | Correct sender; display name and numeric/storage IDs do not work. |
| 401/403 | Check the key, current replyMessage permission, actor, and channel access. |
Retry safety
Gotchas
:eyes: or :smile:. Raw Unicode such as 👍 is not interchangeable. Numeric user_id, display name, and MongoDB _id are unsupported sender values.Next steps
Request
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/messages/react' \
--header 'Authorization: Bearer <communityApiKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"messageId": "<incomingMessage.id>",
"emoji": ":eyes:",
"sender": "community-agent@example.com"
}'Response Response Example
200 - Success Example
{
"status": "success",
"message": "Message reacted successfully"
}Modified at 2026-08-15 05:28:00