Concepts

Services and SMS fallback

How BlueBot chooses between iMessage and a regular text, how a failed iMessage falls back to SMS through your iPhone, and when to ask for one or the other.

Open in Claude Open in ChatGPT .md

A text from BlueBot goes the way a text you send by hand goes: as an iMessage (a blue bubble) to someone on iMessage, or as a regular text (SMS, a green bubble) through your iPhone to anyone else. You choose how much say BlueBot has with service on a send.

The three choices

`service`	What it sends	If it can't
`auto` (the default)	Whatever the newest chat with the person used. iMessage when you've never texted them.	An iMessage that fails and never goes is sent once more as SMS through your iPhone.
`imessage`	An iMessage and nothing else.	The text fails with `failure.reason: "not_on_imessage"`.
`sms`	A regular text through your iPhone.	The text fails with `failure.reason: "messages_refused"`.

POST/v1/messagesSend a text →

curl -X POST "https://usebluebot.com/api/v1/messages" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: open-house-reminder-48213" \
  -d '{
    "to": "+15555550123",
    "text": "Hi Maria, the open house at 412 Oak St starts at 1 PM tomorrow. See you there.",
    "service": "auto"
  }'

Leave service out and you get auto, which is right for almost everything. The message records what you asked for in service_requested and what it went as in service, which stays null until it's sent.

How the SMS fallback works

Sam texts a lead, Priya, for the first time. BlueBot has no chat with her, so auto tries iMessage. Priya has an Android phone, so Messages shows the iMessage failed and never went. Then:

The Mac reports that the iMessage didn't go.
BlueBot queues the same text once more, this time as SMS, and sets sms_retry: true on it. It keeps its place in today's counts, so it doesn't use up a second new person.
The Mac sends it through Sam's iPhone, as a green bubble.
It becomes sent with service: "sms", and message.sent fires. Only one event fires for the whole thing.

Next time Sam texts Priya, the newest chat is SMS, so auto goes straight to SMS.

The fallback happens once, only for an auto text, only to one person (never into a group), and only when Messages shows the iMessage never went. If the SMS fails too, the text fails with not_on_imessage and the detail "The regular text didn't go either."

When to choose `imessage` or `sms`

imessage when a regular text would be wrong: an email address (which can only get iMessage), a picture that has to arrive at full size, or a message you'd rather not send at all than send green. Expect not_on_imessage for people on Android.
sms when you know the person isn't on iMessage, or they've asked for regular texts. It skips the iMessage attempt.
auto for everything else.

To guess before you send, GET/v1/lookup answers what the newest chat with a person used. It's a best guess from your own history, since Apple offers no way to ask about a stranger. Lookups

What reports what

	iMessage	SMS
`sent`	Yes	Yes
`delivered`	Yes, when it reaches their device	Never. An SMS stays `sent`.
`read`	Only if they share read receipts	Never
Pictures and files	Yes, up to 25 MB	Through your iPhone as the carrier allows, which often means smaller pictures or none
To an email address	Yes	No

Messages treats RCS as a regular text, and BlueBot reports it as service: "sms".

Group chats

A text into a group chat (chat_id in place of to) goes as the group's own service: an iMessage group stays iMessage and an SMS group stays SMS. There's no fallback in a group. If Messages can't send to the group, the text fails with "Messages couldn't send it to this group." Group chats

Replies

A text that comes in has service set to what it came by. A contact's last_service is the service of the newest text with them either way, which is what auto uses next time.