> ## Documentation Index
> Fetch the complete documentation index at: https://bluebubbles.anmho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send iMessages with the BlueBubbles SDK

> Send plain text, file attachments, multipart messages with mentions, and tapback reactions to any iMessage chat using the BlueBubbles TypeScript SDK.

The BlueBubbles SDK gives you a set of methods on `client.messages` to send every kind of iMessage your app might need — from a plain text string to richly formatted multipart messages with inline mentions and attachments. Each method maps directly to a BlueBubbles Server REST endpoint, so the behavior you see in the API reference applies here too.

## Send a text message

Use `sendText()` to send a plain text iMessage to any chat. At minimum you need the target chat's GUID, a temporary deduplication ID, and the message body.

```typescript theme={null}
import { BlueBubblesClient } from "bluebubbles-sdk";

const client = new BlueBubblesClient({
  BASE: "http://your-server:1234",
  PASSWORD: "your-server-password",
});

await client.messages.sendText({
  requestBody: {
    chatGuid: "iMessage;+;+15551234567",
    tempGuid: crypto.randomUUID(),
    message: "Hello from BlueBubbles SDK!",
  },
});
```

### All parameters

| Parameter             | Type   | Required | Description                                                                                                  |
| --------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `chatGuid`            | string | Yes      | The GUID of the target chat, e.g. `iMessage;+;+15551234567`                                                  |
| `tempGuid`            | string | Yes      | A unique ID you generate to prevent duplicate sends                                                          |
| `message`             | string | Yes      | The text content to send                                                                                     |
| `method`              | string | No       | `apple-script` (default) or `private-api`                                                                    |
| `subject`             | string | No       | Message subject line — forces `private-api`                                                                  |
| `effectId`            | string | No       | iMessage bubble/screen effect ID — forces `private-api`                                                      |
| `selectedMessageGuid` | string | No       | GUID of the message to reply to — forces `private-api`                                                       |
| `partIndex`           | number | No       | The part index of `selectedMessageGuid` to reply to (default `0`). Requires macOS Big Sur+ and server v1.4.0 |

<Note>
  The `subject`, `effectId`, and `selectedMessageGuid` parameters all require the Private API to be enabled on your BlueBubbles Server. Passing any of them will automatically override `method` to `private-api`. You can also pass `"method": "private-api"` explicitly.
</Note>

### Send a reply

To reply to a specific message, pass `selectedMessageGuid` with the GUID of the message you want to thread under:

```typescript theme={null}
await client.messages.sendText({
  requestBody: {
    chatGuid: "iMessage;+;+15551234567",
    tempGuid: crypto.randomUUID(),
    message: "Got it, thanks!",
    selectedMessageGuid: "ORIGINAL-MESSAGE-GUID-HERE",
    partIndex: 0,
  },
});
```

### Send with an effect

Pass any valid iMessage effect ID in `effectId` to apply a bubble or screen effect:

```typescript theme={null}
await client.messages.sendText({
  requestBody: {
    chatGuid: "iMessage;+;+15551234567",
    tempGuid: crypto.randomUUID(),
    message: "Congratulations!",
    effectId: "com.apple.MobileSMS.expressivesend.confetti",
  },
});
```

***

## Send an attachment

Use `sendAttachment()` to send a file directly to a chat. Pass a multipart form body containing the file and the target `chatGuid`.

<Note>
  `sendAttachment()` conditionally uses the Private API when `method: "private-api"`, `subject`, `effectId`, or `selectedMessageGuid` are included in the request body. Requires BlueBubbles Server 0.3.0+.
</Note>

```typescript theme={null}
import { BlueBubblesClient } from "bluebubbles-sdk";
import { readFileSync } from "fs";

const client = new BlueBubblesClient({
  BASE: "http://your-server:1234",
  PASSWORD: "your-server-password",
});

const formData = new FormData();
formData.append("chatGuid", "iMessage;+;+15551234567");
formData.append("tempGuid", crypto.randomUUID());
formData.append(
  "attachment",
  new Blob([readFileSync("./photo.jpg")], { type: "image/jpeg" }),
  "photo.jpg"
);

await client.messages.sendAttachment({
  requestBody: formData,
});
```

***

## Send a multipart message

`sendMultipartMessage()` lets you combine text, mentions, and pre-uploaded attachments in a single send. Each element in the `parts` array represents one segment of the message.

<Note>
  Before including an attachment in a multipart message, you must upload it first using `client.attachments.uploadAttachment()`. See the [Attachments guide](/guides/attachments) for details.
</Note>

```typescript theme={null}
await client.messages.sendMultipartMessage({
  requestBody: {
    chatGuid: "iMessage;+;+15551234567",
    parts: [
      {
        partIndex: 0,
        text: "Hey, ",
      },
      {
        partIndex: 1,
        text: "Tim Apple",
        mention: "tim@apple.com",
      },
      {
        partIndex: 2,
        text: " check out these photos!",
      },
      {
        partIndex: 3,
        attachment: "UPLOADED-ATTACHMENT-UUID",
        name: "apple.jpg",
      },
      {
        partIndex: 4,
        attachment: "SECOND-UPLOADED-ATTACHMENT-UUID",
        name: "macbook.png",
      },
    ],
  },
});
```

### Parts array rules

* Every element must be a plain object with a `partIndex` (starting at `0`, incrementing by `1`)
* Each part must have either `text` or `attachment` — not both
* Parts with `attachment` must also include a `name` (the filename)
* Attachment values must be UUIDs returned by `uploadAttachment()`, not file paths
* Mention parts must include a `text` label alongside the `mention` address

You can optionally add `subject`, `effectId`, and `selectedMessageGuid` at the top level to use Private API features.

```typescript theme={null}
await client.messages.sendMultipartMessage({
  requestBody: {
    chatGuid: "iMessage;+;+15551234567",
    subject: "Weekly update",
    selectedMessageGuid: "ORIGINAL-MESSAGE-GUID",
    partIndex: 0,
    parts: [
      { partIndex: 0, text: "Here is this week's summary." },
      { partIndex: 1, attachment: "REPORT-UUID", name: "report.pdf" },
    ],
  },
});
```

***

## Send a reaction

Use `sendReaction()` to tapback any message — loves, thumbs up, questions, and so on. This always requires the Private API.

<Note>
  `sendReaction()` requires the Private API to be enabled on your BlueBubbles Server. Requires server version 0.3.0+. The `partIndex` parameter requires macOS Big Sur+ and server v1.4.0.
</Note>

### Valid reaction values

| Value        | Description          |
| ------------ | -------------------- |
| `love`       | Heart                |
| `like`       | Thumbs up            |
| `dislike`    | Thumbs down          |
| `laugh`      | Ha ha                |
| `emphasize`  | Exclamation          |
| `question`   | Question mark        |
| `-love`      | Remove heart         |
| `-like`      | Remove thumbs up     |
| `-dislike`   | Remove thumbs down   |
| `-laugh`     | Remove ha ha         |
| `-emphasize` | Remove exclamation   |
| `-question`  | Remove question mark |

Prefix any reaction with `-` to remove it.

```typescript theme={null}
// Add a heart reaction
await client.messages.sendReaction({
  requestBody: {
    chatGuid: "iMessage;+;+15551234567",
    selectedMessageGuid: "TARGET-MESSAGE-GUID",
    reaction: "love",
    partIndex: 0,
  },
});

// Remove the heart reaction
await client.messages.sendReaction({
  requestBody: {
    chatGuid: "iMessage;+;+15551234567",
    selectedMessageGuid: "TARGET-MESSAGE-GUID",
    reaction: "-love",
    partIndex: 0,
  },
});
```

Use `partIndex` to react to a specific segment within a multipart message. For standard single-part messages, omit it or pass `0`.