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.

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;+;[phone]",
    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;+;[phone]
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

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.

Send a reply

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

await client.messages.sendText({
  requestBody: {
    chatGuid: "iMessage;+;[phone]",
    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:

await client.messages.sendText({
  requestBody: {
    chatGuid: "iMessage;+;[phone]",
    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.

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

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;+;[phone]");
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.

Before including an attachment in a multipart message, you must upload it first using client.attachments.uploadAttachment(). See the Attachments guide for details.

await client.messages.sendMultipartMessage({
  requestBody: {
    chatGuid: "iMessage;+;[phone]",
    parts: [
      {
        partIndex: 0,
        text: "Hey, ",
      },
      {
        partIndex: 1,
        text: "Tim Apple",
        mention: "[e-mail]",
      },
      {
        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.

await client.messages.sendMultipartMessage({
  requestBody: {
    chatGuid: "iMessage;+;[phone]",
    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.

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.

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.

// Add a heart reaction
await client.messages.sendReaction({
  requestBody: {
    chatGuid: "iMessage;+;[phone]",
    selectedMessageGuid: "TARGET-MESSAGE-GUID",
    reaction: "love",
    partIndex: 0,
  },
});

// Remove the heart reaction
await client.messages.sendReaction({
  requestBody: {
    chatGuid: "iMessage;+;[phone]",
    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.