Tapbacks

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.

Send tapback

POST /reactions

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

Field	Type	Required	Description
`message_id`	UUID	Yes	The message being reacted to
`reaction`	string	Yes	One of `"love"`, `"like"`, `"dislike"`, `"laugh"`, `"emphasize"`, `"question"`, or `"eyes"`. `"eyes"` displays as 👀. Arbitrary emoji and `"custom"` are not valid outbound values
`part_index`	integer	No	Part of a multi-part message to react to. Defaults to `0`

Request example

JSON

{
  "message_id": "1a90e8b0-0e1e-485f-b316-28f7dfa96afd",
  "reaction": "like"
}

Response (201)

JSON

{
  "id": "0f6b8a5e-1ca0-4a4f-8e94-44b3e4374f9a",
  "conversation_id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
  "assignment_id": "9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f",
  "target_message_id": "1a90e8b0-0e1e-485f-b316-28f7dfa96afd",
  "direction": "outbound",
  "reaction": "like",
  "custom_emoji": null,
  "remote_number": "+15555550123",
  "part_index": 0,
  "created_at": "2026-06-09T14:31:00Z",
  "updated_at": "2026-06-09T14:31:00Z"
}

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

Status	Description
400	The conversation’s identity is not enabled for iMessage, or the target message cannot accept reactions yet
403	A current recipient is blocked by a contact rule or has opted out (`recipient_opted_out`)
404	Message not found, or not visible to the caller
409	The recipient disconnected, `group_conversation_not_ready` because the group is not ready on its current dedicated line, or current group membership cannot be resolved consistently
422	Unknown `reaction` value (including an arbitrary emoji or `"custom"`), invalid `part_index`, or the target is the agent’s own message (only the human’s messages can be reacted to)
502	Upstream delivery failure — safe to retry. The exception is `reaction_delivery_unconfirmed` (`committed: "unknown"`), where the tapback may already have landed: read the message before sending the same value again, since a repeat can toggle it back off
503	`group_membership_unavailable` because current membership could not be verified; retry with backoff
504	`Reaction could not be sent before the request deadline`; delivery did not begin, so it is safe to retry

Remove tapback

DELETE /reactions/{reaction_id}

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

Status	Description
400	The conversation’s identity is not enabled for iMessage
403	The recipient is blocked by a contact rule or has opted out (`recipient_opted_out`)
404	Reaction not found, or not visible to the caller
409	`reaction_dispatch_in_progress` because a tapback on this message part is still being delivered — including this one, when it was queued and has not settled — the recipient disconnected, `group_conversation_not_ready`, or `group_membership_inconsistent`
422	The tapback was sent by the human, not by your agent
502	`reaction_removal_rejected`, or `reaction_removal_unconfirmed` when the outcome is unknown — safe to retry either
503	`group_membership_unavailable` because current group membership could not be verified; retry with backoff
504	The removal could not be sent before the request deadline; retry

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

bash

curl -X DELETE "https://inkbox.ai/api/v1/imessage/reactions/0f6b8a5e-1ca0-4a4f-8e94-44b3e4374f9a" \
  -H "X-API-Key: YOUR_API_KEY"

Receiving tapbacks

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:

JSON

{
  "id": "5d2c9f4a-3b21-47e0-9c8d-1f6a2b3c4d5e",
  "direction": "inbound",
  "reaction": "custom",
  "custom_emoji": "🌴",
  "remote_number": "+15555550123",
  "part_index": 0,
  "created_at": "2026-06-09T14:32:00Z"
}

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.

Reaction object

Field	Type	Description
`id`	string (UUID)	Reaction ID
`conversation_id`	string (UUID)	The conversation containing the target message
`assignment_id`	string (UUID) \| null	The 1:1 connection carrying the conversation; null for group reactions
`target_message_id`	string (UUID)	The message this tapback targets
`direction`	string	`"inbound"` (from the human) or `"outbound"` (from the agent)
`reaction`	string	`"love"`, `"like"`, `"dislike"`, `"laugh"`, `"emphasize"`, `"question"`, `"eyes"`, or `"custom"`
`custom_emoji`	string \| null	The literal emoji when `reaction` is `"custom"`; null for named outbound reactions, including `"eyes"`
`remote_number`	string	The human’s phone number (E.164)
`part_index`	integer	Message part the tapback targets (`0` for single-part messages)
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

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.

Agent signup API

Agent identity API

Agent2Agent API

Mail API

Phone API

iMessage API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Send tapback

Request body

Request example

Response (201)

Error responses

Remove tapback

Response (204)

Error responses

Example

Receiving tapbacks

Reaction object

​Send tapback

​Request body

​Request example

​Response (201)

​Error responses

​Remove tapback

​Response (204)

​Error responses

​Example

​Receiving tapbacks

​Reaction object

Send tapback

Request body

Request example

Response (201)

Error responses

Remove tapback

Response (204)

Error responses

Example

Receiving tapbacks

Reaction object