Skip to content
Project BlueDocs
Popular pages
Guides / Getting startedQuickstartGet an API key, send your first message, and confirm delivery.API reference / MessagesPOSTSend a messageSend iMessage or SMS, with media, voice memos, and message effects./send-api-messageGuides / IntegrationsWebhooksReceive message and call events at your own endpoint.Guides / Getting startedAuthenticationCreate an API key and authenticate requests with a bearer token.AI tools / AI toolsMCP server & skillConnect Claude, Codex, Cursor, and other AI tools to Project Blue.
↑ ↓ Navigate↵ Openesc Close
Dashboard
For AI agents
View as Markdown

Reactions (Tapbacks)

React to a specific message with one of the six standard iMessage tapbacks. Pass the message_handle from /get-messages-api or /get-message-api as messageHandle.

POST/send-reactionBearer token
iMessage only
Tapbacks only work on iMessage. SMS or RCS targets return status: "ERROR" with Reactions are only supported on iMessage. Reactions on outbound messages are not supported yet.

Request body

messageHandlestringRequired
Opaque message handle from GET /get-messages-api or GET /get-message-api (message_handle). Identifies the message to react to.
reaction"love" | "like" | "dislike" | "laugh" | "emphasize" | "question"Required
One of the six standard iMessage tapbacks.
removeboolean
When true, retracts a previous reaction of the same type on this message. Defaults to false.
partIndexinteger (>= 0)
Which part of a multi-part message to react to. Defaults to 0.

Valid reaction values: love, like, dislike, laugh, emphasize, question. Set remove to true to retract a previous reaction of the same type. A typical pattern is acknowledging an inbound message with like or love instead of (or before) a text reply.

Response

On success the endpoint returns HTTP 200 with { status: "SENT" | "ERROR", messageHandle, reaction, remove, error_message }. Auth and request-validation failures still use standard 4xx bodies with an error field.

API reference