> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blujay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reactions

> Add and remove iMessage tapbacks and emoji reactions on a message.

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.

```bash curl theme={null}
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" }'
```

```javascript Node.js theme={null}
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);
```

```python Python theme={null}
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](https://docs.blujay.io/api-reference/introduction.md).

## 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`.

```bash curl theme={null}
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.

```bash curl theme={null}
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.

```bash curl theme={null}
curl -X DELETE https://api.blujay.io/v1/messages/msg_abc123/reactions/love \
  -H "Authorization: Bearer blu_your_api_key"
```

```javascript Node.js theme={null}
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);
```

```python Python theme={null}
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:

```bash curl theme={null}
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](https://docs.blujay.io/webhooks/events.md#reactions).

## 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](https://docs.blujay.io/webhooks/versions.md).
* **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`](https://docs.blujay.io/errors/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](https://docs.blujay.io/api-reference/introduction.md) and [error codes](https://docs.blujay.io/errors.md).

## Next steps

> [card] [Receive messages](https://docs.blujay.io/messaging/receive-messages.md#reactions)
>
> How your contacts' reactions reach you.

> [card] [Threaded replies](https://docs.blujay.io/messaging/replies.md)
>
> Reply to a specific message in its iMessage thread.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.