Skip to main content

​
Method Signature

await sdk.messages.sendMessage(options: SendMessageOptions): Promise<MessageResponse>
Sends a text message to an iMessage or SMS chat. Supports message effects (confetti, fireworks, etc.), subjects, and rich links.
If the chat doesn’t exist, the SDK will automatically create it using the address extracted from chatGuid.

​
Parameters

​
chatGuid
string
required
The unique identifier for the chat. Format: {service};-;{address} or {service};+;{participants}Examples:
​
message
string
required
The text content of the message to send
​
tempGuid
string
Temporary GUID for tracking the message before server confirmation. Auto-generated if not provided.
​
subject
string
Subject line for the message (typically used in group messages)
​
effectId
string
The effect to apply to the message. See Message Effects for available effect IDs.Examples:
  • com.apple.messages.effect.CKConfettiEffect (confetti)
  • com.apple.messages.effect.CKFireworksEffect (fireworks)
  • com.apple.MobileSMS.expressivesend.loud (loud)
Effects require Private API to be enabled on the BlueBubbles server
​
selectedMessageGuid
string
GUID of a message to reply to or reference
​
partIndex
number
default:"0"
The part index for multi-part messages
​
richLink
boolean
Whether to enable rich link previews for URLs in the message

​
Response

Returns a MessageResponse object:
​
guid
string
Unique identifier for the sent message
​
text
string
The message text content
​
dateCreated
number
Timestamp (milliseconds since epoch) when the message was created
​
tempGuid
string
The temporary GUID used for tracking
​
isFromMe
boolean
Always true for sent messages
​
handle
HandleResponse | null
The handle (contact) associated with the message
​
chats
ChatResponse[]
Array of chats this message belongs to
​
attachments
AttachmentResponse[]
Array of attachments (empty for text-only messages)

​
Examples

​
Basic Text Message

const message = await sdk.messages.sendMessage({
  chatGuid: "iMessage;-;[email protected]",
  message: "Hello, world!"
});

console.log(`Sent message: ${message.guid}`);

​
Message with Confetti Effect

const message = await sdk.messages.sendMessage({
  chatGuid: "iMessage;-;[email protected]",
  message: "Happy Birthday!",
  effectId: "com.apple.messages.effect.CKConfettiEffect"
});

​
Message with Subject

const message = await sdk.messages.sendMessage({
  chatGuid: "iMessage;+;[email protected],[email protected]",
  message: "Meeting notes from today",
  subject: "Team Standup"
});

​
SMS Message

const message = await sdk.messages.sendMessage({
  chatGuid: "SMS;-;+11234567890",
  message: "Hey! This is an SMS message."
});

​
Message with Custom Tracking

import { randomUUID } from "crypto";

const trackingId = randomUUID();
const message = await sdk.messages.sendMessage({
  chatGuid: "iMessage;-;[email protected]",
  message: "Tracked message",
  tempGuid: trackingId
});

console.log(`Tracking ID: ${message.tempGuid}`);

​
Error Handling

try {
  const message = await sdk.messages.sendMessage({
    chatGuid: "iMessage;-;[email protected]",
    message: "Test message"
  });
  console.log("Message sent successfully");
} catch (error) {
  if (error.response?.status === 400) {
    console.error("Invalid chat GUID or message format");
  } else if (error.response?.status === 500) {
    console.error("Server error - check BlueBubbles connection");
  } else {
    console.error("Failed to send message:", error.message);
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us