Skip to main content
The BlueBubbles SDK is a production-ready TypeScript library that wraps the BlueBubbles Server REST API. Whether you want to send iMessages programmatically, automate group chat management, or build a custom messaging client, the SDK gives you typed request/response interfaces, automatic authentication, and a resource-grouped API that runs in Node.js, browsers, and React Native.

Quick Start

Install the SDK and send your first message in under five minutes.

Authentication

Learn how to configure your server password or token credentials.

Guides

Step-by-step walkthroughs for sending messages, managing chats, and more.

API Reference

Complete method reference for every service exposed by the SDK.

​
What you can build

The BlueBubbles SDK lets you interact with iMessage programmatically through a macOS server running BlueBubbles. Common use cases include:
  • Messaging bots — automatically send and respond to iMessages
  • Chat archiving tools — query and export conversation history
  • Notification systems — trigger iMessage alerts from your own applications
  • Group chat automation — create chats, manage participants, set group icons

​
Get started

1

Install the SDK

Add the package to your project with npm or your preferred package manager.
npm install bluebubbles-sdk
2

Connect to your server

Create a BlueBubblesClient pointing at your BlueBubbles Server address and password.
import { BlueBubblesClient } from 'bluebubbles-sdk';

const client = new BlueBubblesClient({
  BASE: 'https://your-server-address',
  PASSWORD: 'your-server-password'
});
3

Make your first call

Query your chats or send a message to verify the connection works.
// List your chats
const chats = await client.chats.list({});

// Send a text message
await client.messages.sendText({
  requestBody: {
    chatGuid: 'iMessage;+;1234567890',
    message: 'Hello from BlueBubbles SDK!'
  }
});
4

Explore the API

Read the Core Concepts to understand GUIDs, the Private API, and how resources are organized.
You need a running BlueBubbles Server on a macOS machine to use this SDK. The SDK communicates with your self-hosted server — it does not connect to any BlueBubbles cloud service.