curl --request POST \
--url https://api.blujay.io/v1/messages/{message_id}/reactions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"type": "love"
}'{
"status": "success",
"data": {
"message_id": "msg_abc123",
"chat_id": "chat_abc123",
"phone_number_id": "phone_abc123",
"operation": "reaction_add",
"status": "accepted",
"reaction": {
"type": "love",
"part_index": 0
}
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:02:00.000Z"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RECIPIENT_SUPPRESSED",
"message": "Recipient is suppressed for outbound messaging",
"type": "authorization",
"http_status": 403,
"retryable": false,
"doc_url": "https://docs.blujay.io/errors/recipient-suppressed",
"details": []
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T00:00:00.000Z"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "PHONE_NUMBER_UNAVAILABLE",
"message": "This service is temporarily unavailable",
"type": "phone_number",
"http_status": 503,
"retryable": true,
"doc_url": "https://docs.blujay.io/errors/phone-number-unavailable",
"details": [],
"retry_after": 30
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T00:00:00.000Z"
}Add a reaction
Adds a tapback to a message in an iMessage chat, from the Blujay phone number the chat belongs to. You can react to messages your contacts sent and to your own. The six standard reactions are love, like, dislike, laugh, emphasize and question. To react with any emoji, send type: custom with emoji set to exactly one emoji, such as 😍 or 👍🏽. A symbol sent without its emoji style, such as ❤, is sent and reported as iPhones send it (❤️). A message can carry one reaction per person on each part, so adding a different one, standard or emoji, replaces yours. Recipients on iOS 17 or earlier see an emoji reaction as the text “Reacted 😍 to …”.
Stickers contacts put on your messages arrive as sticker reactions, but you can’t send stickers (400 VALIDATION_ERROR).
A 202 means Blujay accepted the reaction and is sending it. Confirm it through the reaction.added webhook, where reactor is your phone number. If you already have that reaction on the message, Blujay returns 202 without sending it again. Send an Idempotency-Key so a retry after a lost response is safe.
iMessage only: a message sent or received as SMS or RCS returns 400 UNSUPPORTED_CHAT_OPERATION. A reaction can’t itself be reacted to (404 NOT_FOUND), and an unsent or failed message can’t be either (400 VALIDATION_ERROR). A reaction notifies the other person like a message, so a chat with an opted-out contact returns 403 RECIPIENT_SUPPRESSED, the same rule as sending a message in it.
curl --request POST \
--url https://api.blujay.io/v1/messages/{message_id}/reactions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"type": "love"
}'{
"status": "success",
"data": {
"message_id": "msg_abc123",
"chat_id": "chat_abc123",
"phone_number_id": "phone_abc123",
"operation": "reaction_add",
"status": "accepted",
"reaction": {
"type": "love",
"part_index": 0
}
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:02:00.000Z"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RECIPIENT_SUPPRESSED",
"message": "Recipient is suppressed for outbound messaging",
"type": "authorization",
"http_status": 403,
"retryable": false,
"doc_url": "https://docs.blujay.io/errors/recipient-suppressed",
"details": []
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T00:00:00.000Z"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "<string>",
"type": "validation",
"http_status": 400,
"retryable": true,
"doc_url": "<string>",
"details": [
{}
],
"retry_after": 2,
"reset_at": "2026-10-14T17:01:00.000Z"
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T17:01:00.000Z",
"client_request_id": "<string>"
}{
"status": "error",
"error": {
"code": "PHONE_NUMBER_UNAVAILABLE",
"message": "This service is temporarily unavailable",
"type": "phone_number",
"http_status": 503,
"retryable": true,
"doc_url": "https://docs.blujay.io/errors/phone-number-unavailable",
"details": [],
"retry_after": 30
},
"trace_id": "trc_8f2a1c0e4b7d",
"timestamp": "2026-10-14T00:00:00.000Z"
}Authorizations
Your workspace API key, sent as Authorization: Bearer blu_.... Workspace admins can find it in the Blujay app under API.
An API key has full access to your workspace and works on every endpoint. There is no test mode: every key sends real messages and changes real data, so keep it secret and use it only from your server.
Each API key can make 600 read requests and 120 write requests per minute, plus 60 attachment requests per minute. Over a limit you get 429 RATE_LIMIT_EXCEEDED with Retry-After.
Reseller partner keys. A partner key acts for one of the partner's customers when the request names it in the Blujay-Workspace header (the customer's workspace_ ID). Without the header it reaches only /v1/partner/* and /v1/me. Each customer gets the limits above for each partner key, and all of a partner's requests together get ten times those limits; a 429 says which in error.details[0].scope (partner_customer or partner). A messaging key can read anything for a customer and change chats, messages, contacts, attachments and vCards; everything else needs an admin key (403 PARTNER_ROLE_FORBIDDEN). Paused or closing customers can be read but not changed (409 CUSTOMER_PAUSED or CUSTOMER_CLOSING). Any other workspace ID in the header returns 404 NOT_FOUND; using the header with any other credential returns 400 WORKSPACE_HEADER_NOT_ALLOWED.
Headers
A unique value you choose (1–255 characters) that makes this request safe to retry. Send the same key with the same request and Blujay returns the original response instead of doing the work again. Use a new key for each new action.
Blujay keeps keys for at least 24 hours. Keys are separate for each API key and each route family (for example every POST /v1/chats/{chat_id}/messages shares one). Reusing a key with a different request returns 409 IDEMPOTENCY_REQUEST_MISMATCH. Sending it while the first request is still running returns 409 IDEMPOTENCY_IN_PROGRESS; retry shortly.
1 - 255Path Parameters
^msg_[A-Za-z0-9_-]+$"msg_abc123"
Body
One of Apple's six standard tapbacks, or custom for an emoji reaction (set emoji).
love, like, dislike, laugh, emphasize, question, custom Required with type custom, and not allowed with the standard types.
1"😍"
Which part of the message to react to, numbered the same way as part_index in reaction.added. For a text-only message, 0 is the only part.
x >= 0Response
Blujay accepted the reaction and is sending it from the message's phone number. Confirm it through the reaction.added or reaction.removed webhook. If the reaction was already in place (or already absent), the response is the same and nothing is sent.
Wraps every successful response. The result is in data.
success ^trc_[A-Za-z0-9_-]+$"trc_8f2a1c0e4b7d"
"2026-10-14T17:01:00.000Z"
Show child attributes
Show child attributes
Your X-Request-ID header value, echoed back when you send one. Not included on the send responses (POST /v1/chats and POST /v1/chats/{chat_id}/messages); keep your own mapping from your request ID to the returned message ID there.