Reactions (Tapbacks) API

Send iMessage tapback reactions to messages. Tapbacks are the heart, thumbs up, and other reactions that appear on messages in iMessage — including reactions with any emoji.

Send a Reaction

Add or remove a tapback reaction on a received message.

POST https://api.sendblue.com/api/send-reaction

Request Body

Parameter	Type	Required	Description
from_number	string	Yes	Your Sendblue phone number (E.164 format)
message_handle	string	Yes	The primary message_handle of a received iMessage; do not use an attachment-specific handle
reaction	string	Yes	A named reaction or exactly one emoji (see below)
part_index	number	No	The part to react to when using a multi-part message’s primary handle (default: 0)

Valid Reaction Values

Value family	Add	Remove	Appearance
Classic tapbacks	love, like, dislike, laugh, emphasize, question	prefix with - (e.g. -love)	Apple’s classic heart, thumbs up/down, ha ha, !!, ?
Arbitrary emoji	exactly one emoji, e.g. 🔥, 👍🏽, 👨‍👩‍👧‍👦, 1️⃣	prefix with - (e.g. -🔥)	that exact emoji as the reaction

Values are matched exactly:

• one complete emoji only — composed emoji (skin tones, families, flags, keycaps) count as one;
• no surrounding whitespace and no trimming;
• plain text, text containing an emoji (hello🔥), and multiple emoji (🔥🔥) are rejected;
• names are case-sensitive (Love is rejected); new integrations should send emoji directly (for example 👀);
• use the emoji-picker form: a text-style character without the emoji variation selector (❤ instead of ❤️) is rejected.

Named values resolve before emoji, so love is always Apple’s classic heart tapback, while ❤️ is an emoji reaction with the heart emoji. Likewise emphasize is the classic !! while ‼️ is an emoji reaction.

Example Request

curl -X POST 'https://api.sendblue.com/api/send-reaction' \
  -H 'sb-api-key-id: YOUR_API_KEY' \
  -H 'sb-api-secret-key: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "from_number": "+19175551234",
    "message_handle": "E8F2C3D1-A5B7-4E9F-8C1D-2A3B4C5D6E7F",
    "reaction": "🔥"
  }'

Node.js Example

const axios = require('axios');

// add a classic tapback
await axios.post(
  'https://api.sendblue.com/api/send-reaction',
  {
    from_number: '+19175551234',
    message_handle: 'E8F2C3D1-A5B7-4E9F-8C1D-2A3B4C5D6E7F',
    reaction: 'love'
  },
  {
    headers: {
      'sb-api-key-id': 'YOUR_API_KEY',
      'sb-api-secret-key': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    }
  }
);

// remove an emoji reaction sent earlier
await axios.post(
  'https://api.sendblue.com/api/send-reaction',
  {
    from_number: '+19175551234',
    message_handle: 'E8F2C3D1-A5B7-4E9F-8C1D-2A3B4C5D6E7F',
    reaction: '-👍🏽'
  },
  {
    headers: {
      'sb-api-key-id': 'YOUR_API_KEY',
      'sb-api-secret-key': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    }
  }
);

Success Response (200)

{
  "status": "OK",
  "message": "Reaction request sent",
  "message_handle": "E8F2C3D1-A5B7-4E9F-8C1D-2A3B4C5D6E7F",
  "reaction": "🔥"
}

The reaction field echoes the accepted value, including the - prefix when removing a reaction.

---

Error Responses

Missing from_number (400)

{
  "status": "ERROR",
  "message": "You must specify a valid `from_number` in the request body."
}

Missing message_handle (400)

{
  "status": "ERROR",
  "message": "You must specify `message_handle` in the request body."
}

Invalid Reaction (400)

{
  "status": "ERROR",
  "message": "Invalid reaction. Must be one of love, like, dislike, laugh, emphasize, question, or exactly one emoji (for example 🔥 or 👍🏽), optionally prefixed with - to remove."
}

Invalid part_index (400)

{
  "status": "ERROR",
  "message": "`part_index` must be a non-negative integer."
}

Phone Number Not Found (404)

{
  "status": "ERROR",
  "message": "The from_number is not registered"
}

Message Not Found (404)

The message_handle is unknown or does not belong to this account.

{
  "status": "ERROR",
  "message": "The message to react to was not found for this account"
}

Message Cannot Receive Reactions (422)

The selected message cannot receive a reaction. This includes outbound messages, SMS/RCS messages, attachment-specific handles, App Card messages, and messages received on a different from_number.

{
  "status": "ERROR",
  "message": "unsupported_target",
  "detail": "Reactions are only supported on iMessage messages."
}

Reactions Not Supported for This Number (422)

Not every Sendblue phone number supports reactions. If the specified from_number does not, both classic and emoji reactions return 422.

{
  "status": "ERROR",
  "message": "unsupported_on_this_line",
  "detail": "This line cannot deliver reactions."
}

Notes

1. Primary message handle: Use the received message’s primary message_handle. For a message with attachments, keep the primary handle and use part_index to select a part; an attachment-specific handle returns 422.

2. iMessage Only: Reactions (tapbacks) are only supported for iMessage conversations. Requests targeting SMS or RCS messages are rejected with 422 before anything is sent.

3. App Cards: App Card messages cannot currently receive reactions and return 422.

4. Missing messages: An unknown handle or a handle owned by another account returns 404. A known message that cannot receive reactions returns 422.

5. Phone number support: The API checks whether the specified from_number supports reactions. Unsupported numbers return 422.

6. Removing reactions: Prefix any accepted value with - (-love, -🔥) to remove a reaction you previously sent with that exact value.

7. Timing: Reactions can be sent to messages received within the last few days. Very old messages may not accept reactions.

8. Multi-part Messages: Use part_index with the primary handle when reacting to a specific part of a multi-part message (e.g., an image in a message that also has text).