Does Your AI Agent Know When an iMessage Was Actually Read?

A developer wiring a Claude agent to text leads through Beam asks some version of this almost every week: can the agent check whether the last message got read, so it stops nagging someone who already saw it. The honest answer disappoints anyone who assumed the blue "Read" label inside Messages is just another field waiting on a webhook. It isn't, and reaching for a timer instead is the kind of guess that gets an agent muted.

Beam is an independent messaging platform connecting iMessage, RCS and SMS fallback to a business number. It is not an Anthropic product or an Apple product, and the gap described here sits on Apple's side, not because Beam holds anything back.

Before arguing about webhooks, it helps to be precise about what a human actually sees. Apple's Messages app has a per-contact setting called Send Read Receipts, controlled by the recipient's own device, that puts a small "Read 10:42 AM" label under a message once it's opened (Apple: turn read receipts on or off). Turn it off for one contact and that person never sees the label again. Apple's documentation is explicit that the setting only applies to iMessage, not SMS, which is the first hint that nothing about it was built with a third party's webhook in mind. The label itself is rendered by the Messages app, reading a signal that travels between the two participating Apple IDs. It's a courtesy between two people texting each other, not an integration point for a business platform sitting in front of a provisioned number, so a developer who assumes "Read" is a simple status field waiting on an API is assuming wrong. It isn't exposed the way a delivery receipt is.

The architecture explains the gap better than any policy decision would. Apple's read receipt travels directly between the sending and receiving Apple ID over Apple's own infrastructure; a platform like Beam sits in front of a number and a conversation history, not inside that Apple-to-Apple handshake. PubNub's writeup of how chat apps typically implement read receipts describes the pattern plainly: a client-side read event fires locally on the recipient's device, and that client is the one publishing it onward to any receipts channel a backend listens to (PubNub: read receipts pattern for realtime chat apps). On iMessage, the recipient's device is Apple's own app, not a client Beam controls, so there's nowhere for that onward publish to go.

Some vendors in this space advertise forwarding Apple's read signal as a webhook. Treat that as a feature to verify against current documentation, not a guaranteed property of iMessage, since it depends on infrastructure access Apple doesn't formally document as a third-party integration point. A follow up gate that assumes a read event might never arrive is the safer default regardless of platform, which happens to be where Beam's own catalog already puts you.

Every event Beam pushes to your endpoint arrives as one POST with the same outer shape: an id, a type string naming which event it is, a timestamp, and a data object whose fields change with the type. A message.received event, the one that fires when a contact texts back, carries the sender's number, your number, the body, the channel it arrived on, and any attachments. A message.sent event carries the message id, both numbers, the body, the channel, and who sent it, since an outbound message can come from a teammate, the assistant, or your own API call. A message.failed event carries just enough to identify what died: the id, the recipient, and the body.

Signature verification follows the pattern most webhook systems use: a header carrying a timestamp and an HMAC-SHA256 signature computed over that timestamp joined to the exact raw request bytes, checked against your own signing secret with a constant-time comparison. The raw bytes matter because parsing the JSON and re-serializing it before checking produces different bytes than what was signed, so a genuine event can fail verification for a reason that has nothing to do with whether it's real.

type BeamEvent = {
  id: string;
  type: "message.received" | "message.sent" | "message.failed" | "contact.opted_out" | "assistant.booked" | "assistant.handoff";
  timestamp: number;
  data: Record<string, unknown>;
};

const conversationState = new Map<string, { deliveredAt?: number; replied?: boolean; optedOut?: boolean }>();

function handleBeamEvent(event: BeamEvent) {
  const phone = String(event.data.from ?? event.data.to ?? event.data.phone ?? "");
  const state = conversationState.get(phone) ?? {};
  if (event.type === "message.received") state.replied = true;
  if (event.type === "contact.opted_out") state.optedOut = true;
  if (event.type === "message.sent" && (event.data as { sender?: string }).sender === "bot") {
    state.deliveredAt = event.timestamp;
  }
  conversationState.set(phone, state);
}

function shouldSendFollowUp(phone: string, waitWindowSeconds: number): boolean {
  const state = conversationState.get(phone);
  if (!state || state.optedOut || state.replied || !state.deliveredAt) return false;
  return Date.now() / 1000 - state.deliveredAt >= waitWindowSeconds;
}

This is deliberately plain: a per-phone record built from events Beam actually sends, a function that returns false the instant a reply or opt out shows up, and a wait window measured from delivery rather than from the moment your own code fired the send. A production version wants that state in a real store, plus a reconciliation pass for any webhook delivery that never arrived.

Beam picks the channel automatically, blue bubble when the recipient's phone supports it and plain text otherwise, so an agent built on top of it has to handle both outcomes from one code path rather than assuming every lead is reachable over iMessage. For a contact who falls back to SMS, "was it read" was never answerable on that channel by anyone, on any platform; delivered is the ceiling, not a limitation specific to Beam. Build the fallback rule around that ceiling: treat delivered as the strongest timing signal that will ever exist for a non-iMessage contact, and lean more heavily on the reply check, since no richer signal is coming. This matters most for an agent that reuses one wait-window constant across every contact without checking which channel it landed on; holding a follow up open longer for an SMS contact than for a blue bubble one buys nothing. If your agent already pulls the channel field off the message object to decide tone or attachment handling, reuse that same field to pick the wait window too.

For the full tool catalog and permission model behind read, train, send and book access, our iMessage MCP server guide goes deeper than the single question answered here. If your agent calls Beam's REST or MCP surface directly rather than through a hosted Claude client, our guide to handling Beam's MCP rate limit in a custom agent covers the request budget these webhook checks live inside. Claude Desktop and Claude Code reach the same workspace through a different wiring path, covered in our Claude Desktop MCP bridge guide, and our Claude iMessage overview lays out how the pieces fit together. For every reply reconciled into a CRM's own timeline, not just Beam's, Beam's iMessage CRM sync guide covers the two-way piece this article assumes is already running underneath the handler.