Skip to main content
POST
/
api
/
messages
/
react
Send Reaction
curl --request POST \
  --url https://app.tuco.ai/api/messages/react \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "messageId": "<string>",
  "reaction": "<string>"
}
'
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.

​
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. 
Authorization: Bearer tuco_sk_xxxxxxxxxxxxx

​
Request body

​
messageId
string
The Tuco message ID to react to. Required.
​
reaction
string
Required reaction type.Supported values:
  • "love"
  • "like"
  • "dislike"
  • "laugh"
  • "emphasize"
  • "question"

​
Example

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)

{
  "ok": true,
  "reaction": "love"
}

​
Error responses

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