reaction.tapback

POST /v1/commands/reaction.tapback

Applies one of the six classic tapbacks to any message you can still see, in a direct message or a group. This is the reaction command you almost always want; reaction.apply is a narrower, older variant.

Routing path: agent-turn. Honours Idempotency-Key.

Target

A conversation target, DM or group.

Payload

Request

curl $MAPIER_BASE_URL/v1/commands/reaction.tapback \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": {
      "kind": "conversation",
      "conversationId": "a0000000-0000-4000-8000-000000000001"
    },
    "payload": { "reaction": "love", "targetMessageExternalId": "guid-1" }
  }'

Removing it again is the same call with remove:

{ "reaction": "love", "targetMessageExternalId": "guid-1", "remove": true }

Response

{ "commandId": "cmd-2", "status": "queued", "disposition": "queued" }

A reaction that was added, one that was removed, and one that was already in the state you asked for all settle succeeded with errorCode: null. The settlement event carries no field distinguishing them, so the stream cannot tell you whether this command was the one that changed anything.

{
  "commandId": "cmd-2",
  "logicalActionId": "cmd-2",
  "status": "succeeded",
  "errorCode": null
}

Errors

The common settlement failure is stale_target — the message aged out of bounded history. React promptly after receiving a message rather than hours later. unsupported_capability is the other failed code you will meet.

tapback_unverified is not a failure: it settles ambiguous, meaning the reaction may have been applied and could not be confirmed.

Capabilities

Requires command.reaction_tapback.v1. Its parameters declare supportsGroups and supportsRemove; a Mac advertising the capability without them will reject those uses with capability_constraint_violation.

Related