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

# Send Reaction

> Send an iMessage tapback reaction to an existing message in your workspace. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON.

<Note>
  Use this endpoint to react to an existing message with a native iMessage tapback.
  The target message must already exist in Tuco and belong to your workspace.
</Note>

## What This Endpoint Does

This endpoint adds a native iMessage reaction to an existing message in a conversation.

It is useful when you want your integration to behave more like a human operator in Unibox, for example:

* acknowledging a message with a quick tapback
* reacting before sending a longer reply
* mirroring a lightweight action a user took in your own system

## Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

```bash theme={null}
Authorization: Bearer tuco_sk_xxxxxxxxxxxxx
```

***

## Request body

<ParamField body="messageId" type="string">
  The Tuco message ID to react to. Required.
</ParamField>

<ParamField body="reaction" type="string">
  Required reaction type.

  Supported values:

  * `"love"`
  * `"like"`
  * `"dislike"`
  * `"laugh"`
  * `"emphasize"`
  * `"question"`
</ParamField>

***

## Example

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/messages/react" \
  -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "6a07878bafb1789f8fcb68e6",
    "reaction": "love"
  }'
```

***

## Response

### Success (`200 OK`)

```json theme={null}
{
  "ok": true,
  "reaction": "love"
}
```

### Error responses

| Status | When                                                                  | Body                                                          |
| ------ | --------------------------------------------------------------------- | ------------------------------------------------------------- |
| `400`  | `messageId` or `reaction` is missing                                  | `{ "error": "messageId and reaction required" }`              |
| `400`  | `reaction` is not supported                                           | `{ "error": "Invalid reaction type" }`                        |
| `400`  | `messageId` is not a valid ObjectId                                   | `{ "error": "Invalid messageId" }`                            |
| `400`  | The target message cannot be resolved to a valid iMessage chat target | `{ "error": "Cannot determine contact phone for reaction" }`  |
| `400`  | The target message has no BlueBubbles message ID                      | `{ "error": "Message has no BlueBubbles ID — cannot react" }` |
| `400`  | The target line is missing required relay credentials                 | `{ "error": "Line not found or missing credentials" }`        |
| `401`  | Missing or invalid API key / session                                  | `{ "error": "Unauthorized" }`                                 |
| `404`  | Message not found in your workspace                                   | `{ "error": "Message not found" }`                            |
| `502`  | BlueBubbles returned an upstream error                                | `{ "error": "BlueBubbles error: ..." }`                       |

***

## Notes

* Reactions are workspace-scoped: you can only react to messages inside your own workspace.
* Sending the same reaction again toggles it off.
* Tuco keeps only one outbound self-reaction per message at a time, matching native iMessage behavior.
* If you also want to receive inbound reactions from leads, see [Message Webhooks](/api-reference/message-webhooks#message-reaction).