Send iMessages with the BlueBubbles 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;+;+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

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

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

Get Started

Core Concepts

Guides

Resources

Send iMessages with the BlueBubbles SDK

Send a text message

All parameters

Send a reply

Send with an effect

Send an attachment

Send a multipart message

Parts array rules

Send a reaction

Valid reaction values

​Send a text message

​All parameters

​Send a reply

​Send with an effect

​Send an attachment

​Send a multipart message

​Parts array rules

​Send a reaction

​Valid reaction values

Send a text message

All parameters

Send a reply

Send with an effect

Send an attachment

Send a multipart message

Parts array rules

Send a reaction

Valid reaction values