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.

Harbor Dental
Can we move my cleaning to Friday at 3?
You are set for Friday at 3.

{"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.

Your server
// waiting for a reaction
Harbor Dental
Your cleaning is Friday at 3.
Reply here if anything changes.

Six reactions.

Pass one as the reaction. Put remove_ in front to take it back.

Heart

love

Thumbs up

like

Thumbs down

dislike

Ha ha

laugh

Exclamation

emphasize

Question mark

question

On anything you can tap.

A message, voice message, photo, video or poll. Not another reaction.

Message
Voice message
Photo
Video
Poll
Another reaction 404 not_found

How it works

  1. Send the reaction. POST /api/imessage/reactions with the message_id of any message on the line, theirs or yours, and a reaction. A reaction goes out from the line of the message it reacts to.
  2. 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.
  3. Your webhook hears about it. A reaction you send comes back as reaction.sent, or reaction.failed. When they react, you get reaction.received with a target_id that points at your message.
Send, take back, receive
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, ...}}
The 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.

Reaction webhook events
EventWhen it firesWhat it carries
reaction.receivedThey reacted to one of your messages.message.kind is reaction and message.target_id is your message. Direction in, status received.
reaction.sentA reaction you sent left the line.Direction out, status sent.
reaction.failedA 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.