iMessage reactions API
Send a tapback on any message with one POST to /api/imessage/reactions. When they react to yours, your webhook gets a reaction.received event.
Pro is $49/month per number. Limits apply to every send.
{"message_id": 44, "reaction": "love"}
React with a tap.
Pick a reaction and it lands on their bubble, the same as in Messages. Tap it again to take it back.
Reactions come back to your server.
When they react to your message, your webhook gets reaction.received. Its target_id points at your message.
Six reactions.
Pass one as the reaction. Put remove_ in front to take it back.
Heart
loveThumbs up
likeThumbs down
dislikeHa ha
laughExclamation
emphasizeQuestion mark
questionOn anything you can tap.
A message, voice message, photo, video or poll. Not another reaction.
How it works
- Send the reaction.
POST /api/imessage/reactionswith themessage_idof any message on the line, theirs or yours, and areaction. A reaction goes out from the line of the message it reacts to. - They see a tapback. It appears on the corner of that bubble on their Apple phone. Your number can react to their messages, and they can react to yours.
- Your webhook hears about it. A reaction you send comes back as
reaction.sent, orreaction.failed. When they react, you getreaction.receivedwith atarget_idthat points at your message.
POST /api/imessage/reactions
{"message_id": 44, "reaction": "love"}
// the reply
{"ok": true, "status": "tapback_sent", "id": 45,
"record": {"kind": "reaction", "direction": "out",
"reaction": "love", "target_id": 44,
"status": "sent"}}
// take it back
{"message_id": 44, "reaction": "remove_love"}
// when they react, your webhook gets
{"event": "reaction.received",
"message": {"kind": "reaction", "target_id": 44, ...}}
reaction is love, like, dislike, laugh, emphasize or question. The full reference is in our docs.The three events
Every reaction arrives as one of these. Zapier has a New Reaction Received trigger for the first.
| Event | When it fires | What it carries |
|---|---|---|
reaction.received | They reacted to one of your messages. | message.kind is reaction and message.target_id is your message. Direction in, status received. |
reaction.sent | A reaction you sent left the line. | Direction out, status sent. |
reaction.failed | A reaction you sent did not leave the line. | Direction out, status failed. |
Limits and plans
404 not_found
There is no such message on the line, or the target is itself a reaction. React to a message, voice message, photo, video or poll.
409 conflict
The message has no iMessage GUID yet because it never went out.
No new contact
A reaction never counts as a new contact. Typing indicators, name and photo sharing and chat backgrounds do not either.
iMessage only
A reaction is an iMessage feature. It has no SMS equivalent.
Group chats
Reactions, replies and polls work in an iMessage group chat.
Plans
Pro is $49/month per number, with 5 new contacts a day per number. Growth has 25+ new contacts a day per number. Details are on the iMessage API page.
Questions
Is there an iMessage reactions API?
Yes. POST /api/imessage/reactions takes a message_id and one of love, like, dislike, laugh, emphasize or question. The tapback shows on the corner of that bubble in Messages, and the send comes back as a reaction.sent webhook event.
How do I send a tapback from code?
Send POST /api/imessage/reactions with the message_id of the message you are reacting to and the reaction. The message can be theirs or yours. The response has the same shape as a send, and the stored record has kind: "reaction".
How do I take a reaction back?
Put remove_ in front of the reaction. remove_love takes back a love.
How do I know when someone reacts to my message?
Your webhook gets reaction.received with kind: "reaction" and a target_id that points at your message. Zapier has a New Reaction Received trigger too.
Can I react to a reaction?
No. You can only react to a bubble: a message, voice message, photo, video or poll. A reaction to another reaction returns 404 not_found.
Do reactions count as new contacts?
No. A reaction never counts as a new contact. Typing indicators, name and photo sharing and chat backgrounds do not either.
Do reactions work in group chats and over SMS?
They work in iMessage group chats. They do not work over SMS, because a reaction is an iMessage feature with no SMS equivalent.
Send your first tapback
Get a number, then send POST /api/imessage/reactions with the id of any message on the line.