reaction.apply

React to the newest incoming message in a direct message, including with arbitrary emoji.

POST /v1/commands/reaction.apply

Reacts to the newest incoming message in a direct message. Narrower than reaction.tapback in two ways — DMs only, newest message only — but it is the only command that can apply an arbitrary emoji rather than one of the classic six.

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

Reach for reaction.tapback unless you need custom emoji. It works in groups, targets any message explicitly, and can remove a reaction.

Target

Direct-message conversations only. A group conversationId is not caught at the boundary — it returns 202 and then settles failed. Use reaction.tapback in groups.

Prop

Type

Payload

Two shapes. Both require the caller to name the message it expects to be newest, which is how the command stays safe against a race with an incoming message.

Classic tapback

Prop

Type

Custom emoji

Prop

Type

Request

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

Response

202 Accepted

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

A reaction that was applied and one that was already there both settle succeeded with errorCode: null; the settlement carries nothing that distinguishes them.

Errors

Status	Code	Cause
`400`	`invalid_conversationId`	Not a UUID
`404`	`conversation_not_found`	Unknown conversation, or another account's
`503`	`no_live_connector`	No Mac available

Settlement failures: stale_target when a newer message arrived before the command ran, and unsupported_capability when custom emoji is not supported.

reaction_unverified settles ambiguous rather than failed — the reaction may have been applied and could not be confirmed afterwards.

Capabilities

Requires command.reaction_apply.v1. Custom emoji additionally requires the capability's supportsCustomEmoji parameter.

This command drives the Mac's UI directly and runs one at a time per host. Sustained high-rate reactions will queue behind each other; prefer reaction.tapback for throughput.

Reactions

Choosing between the two reaction commands.

Reactions

On this page