> ## Documentation Index
> Fetch the complete documentation index at: https://bluebubbles.anmho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# BlueBubbles SDK: TypeScript SDK for iMessage automation

> The BlueBubbles SDK gives you a fully-typed TypeScript client for the BlueBubbles Server REST API. Send messages, manage chats, and access contacts with a clean, resource-grouped API.

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.

<CardGroup cols={2}>
  <Card title="Quick Start" icon="bolt" href="/quickstart">
    Install the SDK and send your first message in under five minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Learn how to configure your server password or token credentials.
  </Card>

  <Card title="Guides" icon="book-open" href="/guides/sending-messages">
    Step-by-step walkthroughs for sending messages, managing chats, and more.
  </Card>

  <Card title="API Reference" icon="code" href="/api/messages">
    Complete method reference for every service exposed by the SDK.
  </Card>
</CardGroup>

## 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

<Steps>
  <Step title="Install the SDK">
    Add the package to your project with npm or your preferred package manager.

    ```bash theme={null}
    npm install bluebubbles-sdk
    ```
  </Step>

  <Step title="Connect to your server">
    Create a `BlueBubblesClient` pointing at your BlueBubbles Server address and password.

    ```typescript theme={null}
    import { BlueBubblesClient } from 'bluebubbles-sdk';

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

  <Step title="Make your first call">
    Query your chats or send a message to verify the connection works.

    ```typescript theme={null}
    // 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!'
      }
    });
    ```
  </Step>

  <Step title="Explore the API">
    Read the [Core Concepts](/concepts/client) to understand GUIDs, the Private API, and how resources are organized.
  </Step>
</Steps>

<Note>
  You need a running [BlueBubbles Server](https://bluebubbles.app) 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.
</Note>