Skip to main content
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;+;+15551234567",
    tempGuid: crypto.randomUUID(),
    message: "Hello from BlueBubbles SDK!",
  },
});

​
All parameters

ParameterTypeRequiredDescription
chatGuidstringYesThe GUID of the target chat, e.g. iMessage;+;+15551234567
tempGuidstringYesA unique ID you generate to prevent duplicate sends
messagestringYesThe text content to send
methodstringNoapple-script (default) or private-api
subjectstringNoMessage subject line — forces private-api
effectIdstringNoiMessage bubble/screen effect ID — forces private-api
selectedMessageGuidstringNoGUID of the message to reply to — forces private-api
partIndexnumberNoThe 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;+;+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: 
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.
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;+;+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.
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;+;+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. 
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.
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

ValueDescription
loveHeart
likeThumbs up
dislikeThumbs down
laughHa ha
emphasizeExclamation
questionQuestion mark
-loveRemove heart
-likeRemove thumbs up
-dislikeRemove thumbs down
-laughRemove ha ha
-emphasizeRemove exclamation
-questionRemove question mark
Prefix any reaction with - to remove it. 
// 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.