Message states

Every message has a state. A text you send moves forward through a few of them and stops at one that's settled; a text that comes in is received and stays there. Each move fires a webhook, so you never need to poll to find out what happened.

The states

"Settled" means the text won't move again on its own, apart from sent going on to delivered and read. unconfirmed isn't settled: it waits for you to say what happened.

Every move and its webhook

A text that goes straight from sent to read fires both message.delivered and message.read, in that order. Tapbacks, edits and unsends don't change a text's state: they fire reaction.added, reaction.removed, message.edited and message.unsent.

The message on every event is the whole message as GET/v1/messages/{id} would answer at that moment, with your metadata. A handler can act on the event alone.

When each happened

Every move stamps a time on the message, in UTC: created_at, queued_at, sending_at, sent_at, delivered_at, read_at, failed_at, unconfirmed_at, expired_at, canceled_at, and received_at for a text in. A stamp is null until its move happens. send_at and expires_at are when a text is due and when it gives up.

Why a text failed

A failed text has failure.reason, a code to program against, and failure.detail, what the Mac saw in words.

A failed text is never retried by BlueBot. If you want to try again, send a new text.

Why a text was canceled

Only a scheduled or queued text can be canceled. Once the Mac has claimed it (sending), it's in Messages' hands and the cancel answers conflict. Change or cancel a text

Settle an unconfirmed text

Now and then the Mac hands a text to Messages and can't tell whether it went: Messages didn't show it sent within 30 seconds, or the Mac lost its connection mid-send. BlueBot never guesses and never sends it again on its own, because the person might get it twice. The text becomes unconfirmed and waits for you.

Often it settles itself: if the Mac later finds the text in Messages, or iMessage reports it delivered, it becomes sent and message.sent fires. Otherwise, look at the conversation in Messages and tell BlueBot what happened:

curl -X POST "https://usebluebot.com/api/v1/messages/msg_1Hq2LxW9cVbN3mKpRtYs0a/resolve" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: resolve-msg_1Hq2LxW9cVbN3mKpRtYs0a" \
  -d '{
    "action": "mark_sent"
  }'

• mark_sent when the text is there in the conversation. It becomes sent with resolution: "marked_sent", and message.sent fires.
• send_again when it isn't. BlueBot queues a new text with the same words, files, service and metadata. The old one stays unconfirmed with resolution: "resent" and points to the new one in resent_message_id.

The dashboard's home page lists every unconfirmed text, and GET/v1/device counts them in unconfirmed_count.

Texts you typed yourself

The Mac copies both directions of the conversations it reads. A text you type by hand in Messages on your Mac or iPhone arrives as a message with direction: "out", state: "sent" and source: "mac", and fires message.sent. It was never queued, so it has no hold, no metadata and no queued_at. Your handlers can tell it apart by its source.

Watch state without polling

Reading a text back with GET/v1/messages/{id} is fine while you test. In an app, a webhook for message.sent, message.failed, message.expired and message.unconfirmed tells you when anything settles, and costs nothing against your rate limit. If your server was down, GET/v1/events has the last 30 days.