iMessage Delivered vs Read: What Your Agent Can Confirm

The honest answer involves two mechanics, not one clean webhook. Beam's status progression runs queued, then sent, then delivered or failed, cancelled, or no_channel, living on the message object fetched with a call to Get a Message by id. A sent webhook fires the moment a message is handed to the network, covering the first touch, the inbox, the assistant or a direct API call. Sent is a waypoint, not the finish line.

Nothing in Beam's documented event catalog pushes a dedicated delivered event the instant a message lands. The way to get a confirmed delivered state is to poll that same message by id until its status moves past sent, or reconcile a batch of recent sends on a schedule rather than trusting the webhook stream alone for anything you cannot afford to miss. Beam's webhook delivery pushes once with no automatic retry, so a dropped delivery to your endpoint should never be the only thing standing between your agent and knowing a message landed.

The same competitor documentation draws the sent versus delivered line in almost identical terms: "One means we dispatched the message; the other means it arrived. Only the second is delivery" (Linq: message status webhooks). Build your reconciliation loop around that sentence and a network handoff will never pass for a confirmed arrival again.

Once the three signals are separated, the handler logic mostly writes itself. Here is the order we build it in for an agent that needs to know whether a text actually landed before deciding what to do next.

1. Capture the id and the initial status from the send response, and store it against whatever record triggered the send, a reminder, an appointment confirmation, a follow up.
2. On a message.sent webhook, update that record to reflect the network handoff, but do not treat the action tied to that message as confirmed yet.
3. On a message.failed webhook, route immediately to a recovery path, a retry, a different channel, or a human alert, rather than letting a timer run out on a message that already died.
4. For anything time sensitive enough to need proof of arrival, such as a one time passcode or a same day appointment reminder, call Get a Message and check for a delivered status before telling the rest of your system the job is done.
5. On any message.received webhook tied to that phone number, treat the reply as the strongest available signal and cancel any pending follow up logic outright.
6. On a contact.opted_out webhook, stop everything tied to that number immediately, since sending anything further after a STOP is a compliance problem, not a timing one.

Screenshot: a workspace's Event webhooks settings page with the signing secret visible, next to a small log table showing message.sent, message.failed and message.received rows for one phone number in time order, each tagged with the status it resolved to.

The handler itself stays small on purpose. A per message record built from the events you actually receive, plus one scheduled pass that checks anything still sitting in sent, covers the whole chain described above.

type BeamEvent = { id: string; type: string; data: Record<string, unknown> };
const sendRecords = new Map<string, { status: string; repliedPhone?: string }>();

function handleBeamEvent(event: BeamEvent) {
  const data = event.data as { id?: string; from?: string };
  if (event.type === "message.sent" || event.type === "message.failed") {
    sendRecords.set(String(data.id), { status: event.type === "message.sent" ? "sent" : "failed" });
  }
  if (event.type === "message.received") {
    for (const record of sendRecords.values()) record.repliedPhone = String(data.from);
  }
}

async function confirmDelivered(id: string): Promise<boolean> {
  const res = await fetch(`https://beam.aisync.link/v1/messages/${id}`, {
    headers: { "x-api-key": process.env.BEAM_KEY! },
  });
  const message = await res.json();
  if (message.status === "delivered") sendRecords.set(id, { status: "delivered" });
  return message.status === "delivered";
}

Notice what the code never does: it never checks for a read status, since no such field exists on the message object, and it never treats the send response as more than a starting point. Every state past that comes from a webhook that actually fired or a status check your own code made on purpose.

Run this sequence against a number you control before pointing any of the logic above at a real lead list.

1. Send one test message and confirm the send response returns status queued, not delivered, and that your code records it that way rather than marking the action complete.
2. Confirm a message.sent webhook arrives at your endpoint, and verify the signature before trusting the payload.
3. Call Get a Message on that same id and confirm the status eventually reads delivered, then check that your code only confirms time sensitive actions once that call returns.
4. Send a message to a number you then block or make unreachable, and confirm a message.failed webhook fires and your recovery path runs instead of a silent timeout.
5. Reply to the test message from the recipient side and confirm the message.received webhook cancels any pending follow up in your test data.
6. Kill your webhook endpoint for a minute, send a message during that window, and confirm your scheduled reconciliation pass still catches the eventual status once the endpoint comes back.
7. Only move to real contacts once steps one through six each behaved the way this guide describes, with no step requiring you to guess at a read status that never showed up.