Beam
Text us

imessage tapback api

By · Updated

Does a Claude iMessage Agent See Tapback Reactions?

A tapback is not a text message. It is a separate signal in Apple's private messaging layer, and whether a Claude-powered iMessage agent "sees" it depends entirely on the bridge underneath it. Beam records a reaction on the conversation but does not fire a dedicated webhook for it, so an agent that only listens for webhooks reads a tapback as silence unless it also checks conversation history directly.

Beam is an independent messaging platform, not an Anthropic or Apple product.

Checklist card for Verify Tapback Detection Before Launch: Read your bridge event catalog, Choose detection method, Update state machine, Log which path catches it

What Exactly Is a Tapback Inside Apple's Private Messaging Layer?

We build and support Claude agents that run on top of iMessage, and this exact mismatch, a contact reacting while the agent keeps waiting for text, is one of the first gaps we check before any agent goes live. It is a quiet failure mode: the agent looks broken, the contact thinks they already answered, and nobody is actually wrong.

A tapback is what Apple calls the heart, thumbs up, thumbs down, "HAHA," exclamation, and question mark reactions a contact can leave on a bubble by holding it down. Under the hood, a tapback is not a new row of the same type as a text message. BlueBubbles' own documentation of Apple's private IMCore layer describes a tapback as an "associated message": it carries an associatedMessageGUID that points back at the message being reacted to, plus an associatedMessageType integer that encodes which reaction was used, love as 2000, like as 2001, dislike as 2002, laugh as 2003, emphasize as 2004, and question as 2005, with a negative version of each code in the 3000 range when a reaction is removed instead of added (BlueBubbles IMCore documentation).

That distinction matters more than it sounds like it should. Any bridge or agent written to watch for "a new message arrived" is, structurally, watching for one kind of row in Apple's chat database. That tapback row points at an old message instead of introducing a new one, which makes it a different kind of row entirely. Missing it is not a bug in the usual sense; it is the predictable result of code that was never told this second row type exists.

Beam is an independent messaging platform, not a product built by Anthropic or Apple, and it sits between a Claude agent and that same private layer so the agent never has to parse associated messages itself. But "Beam handles it" and "Beam pushes it to your agent the instant it happens" are two different claims, and the gap between them is the whole point of this guide.

Does a Claude-Powered iMessage Agent Running on Beam See a Tapback as an Event It Can Act On?

Beam exposes tapbacks on the sending side without much friction. Your connected agent can call POST /v1/reactions with a to, a message (the exact text of the message being reacted to), and a tapback of love, like, dislike, laugh, emphasize, or question, plus an optional action of add or remove. That is how an agent lands a heart on a lead's "sounds great" without typing a word back, and it is a deliberate, on-demand action your agent's own code chooses to take.

Receiving one is where the behavior gets less obvious. Beam's documented event webhook catalog lists six types: message.received, message.sent, message.failed, contact.opted_out, assistant.booked, and assistant.handoff. That list stops at six; a reaction landing on one of your outbound messages is not a seventh type in it. The signal does not disappear, though: Beam's own docs describe conversation history as returning recent messages along with their recorded status and reactions, which means the information exists, it just does not arrive the way a new inbound text does. An agent built only to react to webhook pushes will treat a contact's heart tap as nothing happening at all, while a second code path that actually reads the conversation would see it right there.

Our iMessage MCP server guide covers which tools a connected Claude agent gets for reading a conversation versus only listening for pushed events, and that distinction is exactly the one that decides whether your agent notices a tapback or quietly ignores it. If your agent only has a webhook handler and no scheduled or on-demand read of conversation history, a reaction is a blind spot by design, not a bug you can patch inside the webhook handler itself.

How Do Different iMessage Bridges Compare on Reaction Support?

Not every bridge behind an AI agent treats tapbacks the same way, and the differences are not cosmetic. We looked at three distinct approaches: Beam's hosted API, a self-hosted Mac server built around Apple's private API, and a local command-line toolkit that talks to the same private layer directly.

Bridge Send a tapback via API? Remove a tapback via API? How you detect an inbound tapback Source
Beam (Claude agent via MCP or webhooks) Yes, POST /v1/reactions with six reaction types Yes, same endpoint with action set to remove No dedicated webhook event fires; it appears in conversation history Beam iMessage MCP server guide
A self-hosted Mac server built on Apple's private API Yes, through its own private API bridge Yes, a separate negative type code Depends on which server events you have turned on; check your own configuration rather than assume BlueBubbles IMCore documentation
A local Rust command-line toolkit Yes, including sticker and emoji tapbacks Yes Reads the associated-message row directly out of the local Messages database imessage-rs

The self-hosted server and the local toolkit both run against the actual Messages app on a Mac, using Apple's private API rather than a cloud service, which is why they can read a tapback the moment it lands in the local database. The local toolkit in particular exists in part because other tools in this space left full tapback support, including stickers, as a gap; it closes that gap by injecting directly into Messages rather than going through a hosted intermediary. Beam's hosted API trades that local database access for not running a Mac yourself, and the cost of that trade is a reaction that has to be pulled rather than pushed.

That trade is a reasonable one for most agencies and teams, since keeping a dedicated Mac online around the clock just to run a chat bridge is its own maintenance burden, with its own power outages, macOS updates, and physical access problems. The tradeoff only becomes a real cost if nobody on the team realizes it exists. An agent built against a hosted API still needs the same discipline a locally-hosted setup gets for free: something has to actively look for the reaction, on a schedule or on demand, because nothing is going to tap the agent on the shoulder and announce that it arrived. Teams that skip this step tend to discover it the same way: a contact who is certain they already answered, paired with an agent that is certain they never did.

Diagram: a split timeline showing two parallel event streams for the same conversation. On the left, a webhook listener receiving message.received and message.sent events with a visible gap where a tapback would be. On the right, a conversation history poll showing the same tapback appearing as a reaction entry attached to the original message, with a callout noting the two streams disagree about whether anything happened at all.

What Should You Check Before You Assume No Reply Means No Response?

"No text reply yet" and "no response yet" are two different claims, and conflating them is how a working agent starts sending a second nudge message to someone who already answered with a thumbs up. Before you wire up any reaction handling, confirm a few things on the specific bridge your agent actually runs on, not on what a different integration does.

  • Read the full event or webhook catalog your bridge documents, not just the events you happened to notice in a quickstart. A reaction missing from that list is not an oversight on your part; it is a design choice somewhere upstream that you now have to work around.
  • Decide how your agent will notice a reaction that never triggers a push: a scheduled poll of conversation history, a check that runs right before your agent would otherwise send a follow-up nudge, or both.
  • Change your agent's "awaiting reply" state machine so a tapback can close out that wait on its own, rather than only a parsed text reply being able to do it. A contact who reacts has responded, even if your agent's logic was only ever written to recognize words.
  • Log which detection path actually caught a given reaction, webhook or poll, so a future support ticket can tell you which one is quietly not working instead of guessing.

Teams confuse a read receipt and a tapback more often than they should, and they are not the same signal. Opening a thread triggers a read receipt, while reacting to a message triggers something else: a response that never needed the keyboard at all. Our guide to delivered versus read status and our guide to read receipts and agent follow-up timing both cover that other signal in depth, and Beam's own guide to read receipts and typing indicators for business texting walks through how those two signals work together on the business side of a conversation.

How Do You Test Tapback Handling Before Real Contacts Ever React?

Run this short procedure on a number and thread you control before any contact can react to a message your agent sent. It slots directly into the broader pre-launch checklist in our guide to testing a Claude texting agent before going live; treat this as the reaction-specific piece of that larger test, not a replacement for it.

  1. Send a fixed outbound test message from your agent to a number you personally control, one you can react to yourself a moment later.
  2. From that controlled phone, acting as the contact, place a tapback on the message your agent just sent. Pick one reaction type and note which one you used.
  3. Watch your agent's webhook handler for the next minute. If your bridge does not document a dedicated reaction event, confirm nothing arrives, on purpose, so you know this is expected behavior rather than a broken listener.
  4. Pull the conversation's message history through whatever read tool your agent actually uses in production, an MCP conversation-read call or a direct API request, and confirm the tapback you placed in step two shows up somewhere in that response.
  5. Check how your agent's own code currently interprets that result. If nothing in your state machine treats a reaction as a closed loop, this is the step where that gap becomes visible instead of theoretical.
  6. If your bridge supports removing a tapback, repeat steps two through four with a removal, and confirm your agent does not count the same reaction twice or treat the removal as a second, unrelated event.
  7. Only once all of that behaves the way you expect, move the same test to a small slice of real contacts before opening the agent to the full list.

Testing a tapback is cheap and safe, precisely because it costs the contact nothing and never shows up as spam. There is no reason to find out how your agent handles one for the first time in front of a real lead who was just trying to say "sounds good" without typing it out.

Before you connect

What do teams ask before they connect?

Does Beam send a webhook when a contact reacts with a tapback instead of replying?

No. Beam's documented event catalog covers message.received, message.sent, message.failed, contact.opted_out, assistant.booked, and assistant.handoff, and a tapback reaction is not one of those six types. The reaction still gets recorded on the conversation, but an agent that only listens for webhooks will not see it arrive the moment it happens.

If my agent sends a tapback by mistake, can it take it back?

It depends on the bridge. Beam's reaction endpoint accepts an action of add or remove, so a wrongly placed tapback can be reversed with a second call. Not every hosted iMessage bridge offers that second option, so check whether removal is even possible before you build retry logic that assumes it is.

Does a tapback from a contact on Android work the same way?

No. A tapback only exists inside an iMessage, blue bubble, thread. A contact on a green bubble RCS or SMS thread cannot leave a true tapback, so your agent will never receive one through that channel. Build your reaction handling for iMessage conversations specifically, not as a catch-all for every channel a number supports.

Do I need to rewrite my agent's reply logic to handle reactions?

Not the reply logic itself. What changes is the state your agent checks before it decides a contact went quiet. Treat a tapback as a valid acknowledgment that can close out a follow-up step on its own, separate from whatever function actually drafts a text reply, and test that path once before real contacts ever react.

Where do these facts come from?

Checked November 2026.

  1. BlueBubbles IMCore documentation
  2. imessage-rs

Start with a conversation

What should your agent send first?

Text our team what you are building. We will walk through MCP, webhooks and the CRM path that fits your workflow.

iMessage delivery depends on the recipient device and settings. SMS fallback remains subject to carrier A2P requirements.

Interactive demo · Simulation
CCClearpath Coaching

iMessage
Today 9:41 AM

Hi! I would love to hear how your coaching works.

Happy to chat. Would Thursday work for a discovery call?

Thursday sounds great! Looking forward to meeting you.

Blue bubbles. Read receipts. Typing.

Type your own, or send a suggestion.

LET’S TALK

Want this for your business?

Try a conversation with the Beam team.

We use your number to prepare your text link and follow up. No spam. Privacy.

Beam is not affiliated with Anthropic or Apple.

Powered by Beam

Let's talk

Start a conversation.

Tell us a little about your business, or text our team directly.

Text us

(480) 486-1869