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" }

The settlement carries one of four outcomes: the reaction was applied, removed, or was already in the requested state (already_reacted, not_reacted). The last two settle as no_effect rather than failed — the end state is what you asked for, so treat them as success unless you specifically care whether you 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. Also possible: tapback_unverified (applied, but not confirmable) and unsupported_capability.

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