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

# Quickstart: Send your first iMessage with the SDK

> Install the BlueBubbles TypeScript SDK, connect to your server, and send a text message in under five minutes with this step-by-step guide.

This guide walks you through installing the SDK, creating a client, and making your first two API calls: listing your chats and sending a text message. You should have a working integration within a few minutes.

<Note>
  You need a running [BlueBubbles Server](https://bluebubbles.app) on a macOS machine before you start. Have your server's network address and password ready. If you haven't set up the server yet, follow the [BlueBubbles Server setup guide](https://bluebubbles.app) first.
</Note>

<Steps>
  <Step title="Install the SDK">
    Add `bluebubbles-sdk` to your project using your preferred package manager.

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

      ```bash yarn theme={null}
      yarn add bluebubbles-sdk
      ```

      ```bash pnpm theme={null}
      pnpm add bluebubbles-sdk
      ```
    </CodeGroup>
  </Step>

  <Step title="Create a client">
    Import `BlueBubblesClient` and construct it with your server's address and password. The `BASE` field is your server's full base URL and `PASSWORD` is the password you configured in the BlueBubbles Server settings.

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

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

    The client exposes a service for each resource group — `client.chats`, `client.messages`, `client.handles`, `client.attachments`, and more. Every request made through those services automatically includes your password as a query parameter.

    <Tip>
      If your BlueBubbles Server is running locally during development, set `BASE` to `http://localhost:1234` (or whichever port you configured). For production use, point it at a public URL or your local network address.
    </Tip>
  </Step>

  <Step title="List your chats">
    Call `client.chats.list` to fetch recent conversations. This confirms the SDK can reach your server and authenticate successfully.

    ```typescript theme={null}
    const response = await client.chats.list({});

    for (const chat of response.data ?? []) {
      console.log(chat.guid, chat.displayName);
    }
    ```

    A successful response returns an object with a `data` array of chat objects. Each chat has a `guid` — a string like `iMessage;+;1234567890` — that you use to identify the conversation in subsequent calls.
  </Step>

  <Step title="Send a text message">
    Use `client.messages.sendText` to send an iMessage. Pass the `chatGuid` of the conversation you want to send to and the message text.

    ```typescript theme={null}
    await client.messages.sendText({
      requestBody: {
        chatGuid: 'iMessage;+;1234567890',
        message: 'Hello from the BlueBubbles SDK!',
      },
    });
    ```

    Replace `iMessage;+;1234567890` with a real chat GUID from the list you fetched in the previous step. The `+` variant addresses a one-on-one iMessage conversation by phone number.
  </Step>
</Steps>

## Next steps

Now that you have a working client, explore the rest of the SDK:

* Read the [Authentication](/authentication) page to understand how credentials work and what to do if a request fails
* Follow the [Sending messages guide](/guides/sending-messages) for handling replies, reactions, and attachments
* Browse the [API reference](/api/messages) for the full method signatures of every service