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.

You need a running BlueBubbles Server 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 first.

1. Install the SDK

   Add bluebubbles-sdk to your project using your preferred package manager.

   npm

   npm install bluebubbles-sdk
   
2. 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.

   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.

   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.

3. List your chats

   Call client.chats.list to fetch recent conversations. This confirms the SDK can reach your server and authenticate successfully.

   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.

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

   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.

Next steps

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

• Read the Authentication page to understand how credentials work and what to do if a request fails
• Follow the Sending messages guide for handling replies, reactions, and attachments
• Browse the API reference for the full method signatures of every service