# 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.

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"`.                           |

```bash
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"
  }'
```

```ts
import BlueBot from '@usebluebot/sdk';

const client = new BlueBot({ apiKey: process.env.BLUEBOT_API_KEY });

const message = await client.messages.send({
  to: '+15555550123',
  text: 'Hi Maria, the open house at 412 Oak St starts at 1 PM tomorrow. See you there.',
  service: 'auto',
}, { idempotencyKey: 'open-house-reminder-48213' });
console.log(message);
```

```python
import os
from bluebot import BlueBot

client = BlueBot(api_key=os.environ["BLUEBOT_API_KEY"])

message = client.messages.send(
    to="+15555550123",
    text="Hi Maria, the open house at 412 Oak St starts at 1 PM tomorrow. See you there.",
    service="auto",
    idempotency_key="open-house-reminder-48213",
)
print(message)
```

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:

1. The Mac reports that the iMessage didn't go.
2. 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.
3. The Mac sends it through Sam's iPhone, as a green bubble.
4. 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."

> **Fallback needs your iPhone.** An SMS from your number leaves from your iPhone, so Text Message Forwarding must be on for the Mac, and your iPhone must be on and connected. Without it iMessages still go, and texts to people who aren't on iMessage fail. The Mac's `forwarding` check tells you. [The Mac app](https://usebluebot.com/docs/concepts/mac-app)

## 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](https://usebluebot.com/docs/sending/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](https://usebluebot.com/docs/sending/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.