Set your reaction to a channel message

PUT/v1/channels/{channelId}/messages/{messageId}/reactions

Requires threads:write and active membership in the selected organization. Sets or removes only the authenticated member's reaction; repeated desired states are idempotent. The message must belong to this channel (channel_message_not_found, 404); archived channels return channel_archived (409). Reactions are persisted in thread.message.reactions.updated events, including the message's original author, sequence and timestamp plus metadata.reactions and a monotonic metadata.reactionsVersion. Read them through the canonical timeline/events API and SSE. They do not change unread activity or enqueue agent runs.

How to call this endpoint

Every ACP API request uses bearer authentication. The examples here show the actual request path, auth header, and body shape that the platform expects.

Path, query, and header parameters

These parameters control which ACP object the endpoint acts on and how the request is processed.

Path parameters

Name	Location	Type	Required	Description
channelId	path	string	Yes	—
messageId	path	string	Yes	—

Query parameters

None.

Body schema

Content type: application/json · Required

Field	Type	Required	Description
emoji	string	Yes	One Unicode emoji grapheme (including joined or skin-tone variants).
selected	boolean	Yes	—

What the API returns

Each response code below includes the documented payload shape for the ACP API.

200Current reactions and their retained canonical event (the source message when an empty state is unchanged)application/json

Field	Type	Required	Description
event	object	Yes	—
event.id	string	Yes	Unique identifier.
event.threadId	string	Yes	Thread ID.
event.sequence	integer	Yes	—
event.type	string	Yes	—
event.producerType	string	Yes	—
event.producerId	string	Yes	—
event.visibility	string	Yes	—
event.payload	object	Yes	—
event.occurredAt	string	Yes	—
event.createdAt	string	Yes	ISO 8601 timestamp.
reactions	object[]	Yes	—
reactions[].emoji	string	Yes	—
reactions[].userIds	string[]	Yes	—
reactions[].count	integer	Yes	—

400Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

401Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

403Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

404Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

409Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

500Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

503Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

Set your reaction to a channel message

Response 200

See the ACP quickstart and SDK flow