Reactions

Add a tapback reaction to a message. The type values are Apple’s six tapback verbs — love, like, dislike, laugh, emphasize, question — plus custom, which carries any single emoji in custom_emoji.

Add or remove a reaction

Use operation to add or remove the reaction:

curl -sS -X POST "https://api.relayapp.im/v1/messages/msg_01JZM3T8AH/reactions" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "operation": "add", "type": "love" }'

Field	Values
`operation`	`add` \| `remove`
`type`	`love` \| `like` \| `dislike` \| `laugh` \| `emphasize` \| `question` \| `custom`
`custom_emoji`	required exactly when `type` is `custom`. Any single emoji, e.g. `"🔥"`
`target_part_id`	optional. The `prt_` id to anchor on; omit it to react to the whole message

Choose a target

A reaction targets a slot: the whole message, or one exact part of it.

curl -sS -X POST "https://api.relayapp.im/v1/messages/msg_01k1m9x2ph4vb7k0d3wzr8ftqe/reactions" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "add",
    "type": "custom",
    "custom_emoji": "🔥",
    "target_part_id": "prt_01k1ma0m5sy2k8f3b7wnq4hdvc"
  }'

target_part_id names a part of any kind. Read the part_id off the part you want from the message itself.

Read the result

A success returns the stored reaction, the same object recipients receive as the data of a reaction.added or reaction.removed event:

{
  "reaction": {
    "message_id": "msg_01k1m9x2ph4vb7k0d3wzr8ftqe",
    "target_part_id": "prt_01k1ma0m5sy2k8f3b7wnq4hdvc",
    "type": "custom",
    "custom_emoji": "🔥",
    "actor": { "kind": "agent", "id": "agt_01k1m7v9wr4t2b8n5c3qjd6hzx" },
    "operation": "add",
    "changed": true
  }
}

actor.kind is user or agent, the same two values a message sender_handle carries. changed says whether anything actually moved. Relay emits reaction.added or reaction.removed only when it is true, so a retry costs recipients nothing.

Case	Result
Add or remove succeeds	The stored reaction, `changed: true`
Remove a missing reaction, or add an existing one	`200` with `changed: false`
Add a second reaction in the same slot	Replaces the first, the way a tapback does
`target_part_id` names no part of this message	`422 invalid_request`
Target outside the agent’s conversations	`403 forbidden`
More than 120 reactions a minute	`429 rate_limited`, with `Retry-After` in seconds

A message projected in history carries its reactions in the flatter reactions[] shape, which uses actor_kind and actor_id in place of a nested actor and adds created_at.

Receiving reaction events

When a user reacts to the agent’s message, the agent’s webhook receives reaction.added or reaction.removed:

{
  "event_id": "evt_01JZR3ACT10N",
  "event_type": "reaction.added",
  "agent_id": "agt_01JZRELAY",
  "created_at": "2026-07-13T20:02:11.000Z",
  "data": {
    "message_id": "msg_01k1m9x2ph4vb7k0d3wzr8ftqe",
    "target_part_id": null,
    "type": "love",
    "actor": { "kind": "user", "id": "usr_01k1m8t3zq7v2r9c4b6ndh5xwj" },
    "operation": "add"
  }
}

changed appears only in the reaction endpoint’s own 200 response; the event fires exactly when it was true, so it carries no changed field.

Use a reaction when acknowledgment is enough. React with like to a “thanks” instead of sending another message.

Next steps

Message model for part identities and reaction slots
Event types
Sending messages

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Add or remove a reaction

Choose a target

Read the result

Receiving reaction events

Next steps

​Add or remove a reaction

​Choose a target

​Read the result

​Receiving reaction events

​Next steps

Add or remove a reaction

Choose a target

Read the result

Receiving reaction events

Next steps