Tapbacks are iMessage's inline reactions — the heart, thumbs-up, "haha", eyes, and friends that attach to a specific message bubble. Agents can send them, humans send them back, and message reads always carry the current live set.

Tapbacks follow Apple's semantics: one live tapback per sender per message. Sending a new tapback to a message you already reacted to replaces your previous one, and your agent can take its own tapback back entirely. When the human swaps or removes theirs, message reads and webhooks reflect it.

---

React to a message a human sent in one of your agent's 1:1 or ready group conversations. iMessage has no concept of reacting to your own messages, so an agent can only tapback an inbound message — targeting one of the agent's own messages returns 422 in either conversation type.

Request body

Request example

Response (201)

If the agent already had a live tapback on that message part, it is replaced — exactly what the human sees happen on their device.

For a group reaction, assignment_id is null and remote_number identifies the participant who sent the target message. The request and the rest of the response use the same shape as 1:1.

Error responses

---

Take back a tapback your agent sent. Pass the reaction id — the one returned when you sent it, or the one on the entry in a message's reactions array. The tapback disappears from the human's message bubble, and it drops out of the reactions array on the next read.

Only your agent's own tapbacks can be removed. A human's tapback belongs to them; targeting one returns 422.

Response (204)

No body. Removing a tapback Inkbox already shows as gone — because you removed it, or because a newer tapback replaced it — also returns 204, without sending anything to the recipient.

Error responses

Every failure leaves the tapback in place rather than clearing it locally, so retrying is the right response to an error — including the unconfirmed one, where the removal may already have reached the recipient. In that case your next read still shows the tapback live until a retry succeeds.

Example

---

Tapbacks from humans in 1:1 and group conversations arrive two ways:

• On message reads — every message object carries a reactions array with the live tapbacks targeting it, oldest first.
• As webhooks — imessage.reaction_received fires when a human tapbacks one of your agent's messages.

Humans can react with any emoji, not just the classic six. Those arrive with reaction: "custom" and the literal emoji in custom_emoji:

Arbitrary custom-emoji tapbacks are receive-only. Outbound sends accept the classic six plus "eyes"; pass the named "eyes" value rather than the literal 👀 emoji.

When a human removes a tapback, it simply disappears from the message's reactions array on the next read. Removals do not fire a webhook.

Group tapbacks use the same target-message semantics: every reaction attaches to one target_message_id and part_index, a new reaction from the same sender replaces their previous reaction on that message part, and a removal clears it. On group reactions, assignment_id is null and remote_number identifies the participant associated with the reaction.

The compact reaction entries embedded in a message's reactions array omit the conversation/assignment/target IDs (they're implied by the message) and the updated_at field.