Skip to main content
The AttachmentsService provides everything you need to work with iMessage file attachments. You can count and inspect attachments by GUID, download them (with an optional force-download for files not yet cached on the Mac), generate BlurHash preview strings for images, retrieve Live Photo counterparts, and upload files to the server before composing multipart messages. Access the service via your initialized client: 
import { BlueBubblesClient } from 'bluebubbles-sdk';

const client = new BlueBubblesClient({ BASE: 'http://your-server:1234', PASSWORD: 'your-server-password' });
const attachments = client.attachments;

​
Attachment metadata

​
getAttachmentCount()

Fetch the total number of attachments stored in your iMessage account on the server device. 
getAttachmentCount(): CancelablePromise<any>
This method takes no parameters. 
const response = await client.attachments.getAttachmentCount();
console.log(response.data); // total attachment count

​
get()

Fetch an attachment’s full database record by its GUID. 
get({ guid }: { guid: string }): CancelablePromise<any>
​
guid
string
required
The GUID of the attachment to look up.
const response = await client.attachments.get({
  guid: 'attachment-guid-here',
});
console.log(response.data); // attachment metadata object

​
getAttachmentBlurhash()

Generate a BlurHash string for an image attachment. You can optionally pre-resize the image before hashing to reduce computation time. 
getAttachmentBlurhash({ guid }: { guid: string }): CancelablePromise<any>
​
guid
string
required
The GUID of the image attachment to generate a BlurHash for.
Generating a BlurHash is computationally intensive. If the attachment is large, consider specifying resize dimensions in the query string (if your server version supports it) to significantly reduce generation time.
const response = await client.attachments.getAttachmentBlurhash({
  guid: 'attachment-guid-here',
});
console.log(response.data); // BlurHash string, e.g. "LKO2?U%2Tw=w]~RBVZRi};RPxuwH"

​
Uploading attachments

​
uploadAttachment()

Upload a file to the server’s iMessage attachments directory. You must call this before including an attachment in a multipart message via MessagesService.sendMultipartMessage(). It is not required when sending a standalone attachment with MessagesService.sendAttachment(). 
uploadAttachment({ requestBody }: { requestBody?: any }): CancelablePromise<any>
​
requestBody
any
Multipart form data containing the file to upload.
The response includes a data.hash string — a unique identifier (UUID) you use as the attachment value in each multipart message part.
Save the returned data.hash value immediately. You will need it when constructing the parts array for sendMultipartMessage().
const formData = new FormData();
formData.append('attachment', fileBlob, 'document.pdf');

const response = await client.attachments.uploadAttachment({
  requestBody: formData,
});

const attachmentHash = response.data.hash;
// Use attachmentHash in sendMultipartMessage() parts

​
Downloading attachments

​
download()

Download an iMessage attachment by its GUID. Returns the file binary. If the file has not been downloaded to the Mac yet, this returns a 404. 
download({ guid }: { guid: string }): CancelablePromise<any>
​
guid
string
required
The GUID of the attachment to download.
If the attachment has not yet been downloaded to the macOS server, this endpoint returns a 404. Use forceDownloadAttachment() instead if you need to trigger a download for an attachment that isn’t cached locally.
const response = await client.attachments.download({
  guid: 'attachment-guid-here',
});
// response contains the raw file bytes

​
forceDownloadAttachment()

Force-download an attachment by GUID, triggering the macOS server to fetch the file from Apple’s servers if it isn’t already cached locally. Requires the Private API. 
forceDownloadAttachment({ guid }: { guid: string }): CancelablePromise<any>
​
guid
string
required
The GUID of the attachment to force-download.
Requires the Private API. Use this method when download() returns a 404 because the file is not yet cached on the Mac. This endpoint will trigger the attachment to be pulled from Apple’s servers before returning the file.
const response = await client.attachments.forceDownloadAttachment({
  guid: 'attachment-guid-here',
});
// response contains the raw file bytes after a successful force-download

​
Live Photos

​
getAttachmentLivePhoto()

Retrieve the Live Photo counterpart (a short .mov video) for an image attachment that was sent as a Live Photo. 
getAttachmentLivePhoto({ guid }: { guid: string }): CancelablePromise<any>
​
guid
string
required
The GUID of the attachment to retrieve the Live Photo for.
If the attachment is not an image or does not have a Live Photo version, this method returns an error indicating that no live photo exists for the given GUID.
const response = await client.attachments.getAttachmentLivePhoto({
  guid: 'attachment-guid-here',
});
// response contains the Live Photo .mov video data