Change, cancel or settle a text

A text can be changed while it’s scheduled, canceled while it’s waiting, and settled by you when the Mac couldn’t tell whether it went. After it goes, it’s in the person’s Messages and nobody can take it back.

What each state allows

Asking for something a state doesn’t allow answers 409 conflict, and error.message names the state the text is in. Texts that came in (received) can’t be changed, canceled or settled. Message states

Change a scheduled text

PATCH/v1/messages/{id} changes the words, the time, the expiry or the metadata of a text that is still scheduled. Send only what changes:

curl -X PATCH "https://usebluebot.com/api/v1/messages/msg_1Hq2LxW9cVbN3mKpRtYs0a" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hi Maria, your cleaning with Dr. Patel moved to Friday at 2 PM. Reply C to confirm.",
    "send_at": "2026-11-20T17:00:00-05:00"
  }'

You can’t change who a text goes to, its service or its files. Cancel it and send a new one instead.

The answer is the changed message. A scheduled text that becomes due fires message.queued; otherwise a change fires no event.

Cancel a text

POST/v1/messages/{id}/cancel stops a text that is scheduled or queued:

curl -X POST "https://usebluebot.com/api/v1/messages/msg_1Hq2LxW9cVbN3mKpRtYs0a/cancel" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Idempotency-Key: cancel-msg_1Hq2LxW9cVbN3mKpRtYs0a"

{
  "id": "msg_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "message",
  "state": "canceled",
  "cancel_reason": "requested",
  "canceled_at": "2026-11-13T19:42:00.000Z",
  "hold": null
}

The text never goes, and message.canceled fires. Canceling a text that is already canceled answers it again with nothing changed, so it’s safe to retry. A text in sending can’t be canceled: the Mac took it, usually within the last few seconds, and it is already on its way to Messages.

cancel_reason says who canceled a text:

To stop everything for a while rather than cancel texts one by one, pause sending instead. Paused texts wait with the paused hold and go when you resume, unless they expire first. Holds

Settle an unconfirmed text

When the Mac takes a text, it has 3 minutes to report what happened. Usually it reports sent within seconds. If those 3 minutes pass with no report, the text becomes unconfirmed and message.unconfirmed fires.

That happens when the Mac lost its connection, went to sleep or restarted partway, or when Messages still hadn’t shown the text as sent 30 seconds after the Mac handed it over. A regular text going through an iPhone that’s out of reach is the usual case. The text may have gone, or it may not have.

BlueBot never sends an unconfirmed text again on its own, because sending a text twice is worse than asking you. You settle it with POST/v1/messages/{id}/resolve:

1. Look at the conversation in Messages on your Mac or iPhone.
2. If the text is there and shows as sent, mark it sent.
3. If it isn’t, or it shows “Not Delivered”, send it again.

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: settle-msg_1Hq2LxW9cVbN3mKpRtYs0a" \
  -d '{
    "action": "mark_sent"
  }'

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: settle-msg_1Hq2LxW9cVbN3mKpRtYs0a-again" \
  -d '{
    "action": "send_again"
  }'

{
  "id": "msg_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "message",
  "state": "unconfirmed",
  "resolution": "resent",
  "resolved_at": "2026-11-13T19:50:00.000Z",
  "resent_message_id": "msg_2Bf8QzD4kJmA6nXwEuTr1c"
}

Settle a text once. Settling it again, or settling a text that isn’t unconfirmed, answers 409 conflict. Send an Idempotency-Key with send_again so a retry can’t queue two new texts.

If a late report comes in from the Mac saying the text went after all, BlueBot records that it was sent, so a text you haven’t settled yet may settle itself.

Find texts that need you

GET /v1/device counts them in unconfirmed_count, and BlueBot’s window on the Mac lists them under Needs you. To read them:

curl "https://usebluebot.com/api/v1/messages?state=unconfirmed" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"

A program that sends many texts should listen for message.unconfirmed and either ask a person or follow a rule you choose. A reminder that has a later reminder coming can usually be marked sent. A one-time code or a payment link should be checked by a person.

What you can’t do

BlueBot can’t edit a text after it’s sent, unsend it, or send a tapback. Messages allows those only through private frameworks in macOS that need System Integrity Protection turned off, and BlueBot won’t ask that of anyone. You can still edit or unsend a text by hand in Messages on your Mac or iPhone, and BlueBot records the change with message.edited or message.unsent. Capabilities