Reactions

Add a tapback, like a heart or a thumbs up, or any emoji to a message in an iMessage chat, and remove it again. Reactions go out from the Blujay phone number in the message’s chat.

Add a reaction

Send the reaction type for a message.

curl -X POST https://api.blujay.io/v1/messages/msg_abc123/reactions \
  -H "Authorization: Bearer blu_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "type": "love" }'

const response = await fetch("https://api.blujay.io/v1/messages/msg_abc123/reactions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLUJAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ type: "love" }),
});
console.log(response.status, (await response.json()).data);

import os
import requests

response = requests.post(
    "https://api.blujay.io/v1/messages/msg_abc123/reactions",
    headers={
        "Authorization": f"Bearer {os.environ['BLUJAY_API_KEY']}",
    },
    json={"type": "love"},
    timeout=60,
)
print(response.status_code, response.json()["data"])

Blujay answers 202 Accepted. The full response is in the API reference.

Reaction types

Type	Shows as
`love`	Heart
`like`	Thumbs up
`dislike`	Thumbs down
`laugh`	”Ha ha”
`emphasize`	”!!”
`question`	”?”
`custom`	The emoji you send in `emoji`

React with an emoji

Send type: "custom" with exactly one emoji in emoji.

curl

curl -X POST https://api.blujay.io/v1/messages/msg_abc123/reactions \
  -H "Authorization: Bearer blu_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "type": "custom", "emoji": "😍" }'

Skin tones, flags and families count as one emoji.
People on iOS 17 or earlier see it as the text “Reacted 😍 to …”.

React to part of a message

A message with several parts, like a text and two photos, takes a reaction on each part. Set part_index to pick one; it defaults to 0, the first part.

curl

curl -X POST https://api.blujay.io/v1/messages/msg_abc123/reactions \
  -H "Authorization: Bearer blu_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "type": "laugh", "part_index": 2 }'

Remove a reaction

Name the reaction in the path. Add ?part_index= if it isn’t on the first part.

curl -X DELETE https://api.blujay.io/v1/messages/msg_abc123/reactions/love \
  -H "Authorization: Bearer blu_your_api_key"

const response = await fetch("https://api.blujay.io/v1/messages/msg_abc123/reactions/love", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.BLUJAY_API_KEY}`,
  },
});
console.log(response.status);

import os
import requests

response = requests.delete(
    "https://api.blujay.io/v1/messages/msg_abc123/reactions/love",
    headers={
        "Authorization": f"Bearer {os.environ['BLUJAY_API_KEY']}",
    },
    timeout=60,
)
print(response.status_code)

It also removes reactions added in the Blujay app. To remove an emoji reaction, use custom and pass the emoji, URL-encoded:

curl

curl -X DELETE "https://api.blujay.io/v1/messages/msg_abc123/reactions/custom?emoji=%F0%9F%98%8D" \
  -H "Authorization: Bearer blu_your_api_key"

Confirm with webhooks

Event	When
`reaction.added`	A reaction was added, by you or by a contact.
`reaction.removed`	A reaction was removed.

reactor tells you who reacted: one of your numbers, or the contact’s phone or email. See the full payload on Webhook events.

Emoji and stickers you receive

Emoji reactions arrive as type: "custom" with emoji.
Stickers a contact puts on a message arrive as type: "sticker" with sticker: the image’s attachment_id, file details and download_url.
Webhooks: payload version 2026-10-30 sends both as reaction.added and reaction.removed. Earlier versions get them as message.received. See Payload versions.
Message reads: GET /v1/messages/{message_id} lists the message’s current reactions, emoji and stickers included.

Good to know

iMessage only. The message must be sent; one that is still sending, failed or was unsent can’t take a reaction.
One reaction per person per part. A new reaction replaces your old one. Sending one you already have, or removing one you don’t, returns 202 and sends nothing.
202 means accepted, not delivered. Wait for reaction.added. Retrying is safe: a reaction you already have sends nothing.
No stickers. You can’t send or remove a sticker (400 VALIDATION_ERROR).
Not messages. Reactions never appear as messages in lists. Each message read carries its current reactions; message webhooks don’t.
Errors. Each one links to its fix from the API reference and error codes.

Guides

Add a reaction

Reaction types

React with an emoji

React to part of a message

Remove a reaction

Confirm with webhooks

Emoji and stickers you receive

Good to know

Next steps

Receive messages

Threaded replies

​Add a reaction

​Reaction types

​React with an emoji

​React to part of a message

​Remove a reaction

​Confirm with webhooks

​Emoji and stickers you receive

​Good to know

​Next steps

Receive messages

Threaded replies

Add a reaction

Reaction types

React with an emoji

React to part of a message

Remove a reaction

Confirm with webhooks

Emoji and stickers you receive

Good to know

Next steps