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

# Attachments API reference — BlueBubbles SDK

> Upload, download, and inspect iMessage attachments — including blurhash previews and Live Photos — using the BlueBubbles SDK AttachmentsService.

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:

```typescript theme={null}
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.

```typescript theme={null}
getAttachmentCount(): CancelablePromise<any>
```

This method takes no parameters.

```typescript theme={null}
const response = await client.attachments.getAttachmentCount();
console.log(response.data); // total attachment count
```

***

### `get()`

Fetch an attachment's full database record by its GUID.

```typescript theme={null}
get({ guid }: { guid: string }): CancelablePromise<any>
```

<ParamField path="guid" type="string" required>
  The GUID of the attachment to look up.
</ParamField>

```typescript theme={null}
const response = await client.attachments.get({
  guid: 'attachment-guid-here',
});
console.log(response.data); // attachment metadata object
```

***

### `getAttachmentBlurhash()`

Generate a [BlurHash](https://blurha.sh) string for an image attachment. You can optionally pre-resize the image before hashing to reduce computation time.

```typescript theme={null}
getAttachmentBlurhash({ guid }: { guid: string }): CancelablePromise<any>
```

<ParamField path="guid" type="string" required>
  The GUID of the image attachment to generate a BlurHash for.
</ParamField>

<Note>
  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.
</Note>

```typescript theme={null}
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()`.

```typescript theme={null}
uploadAttachment({ requestBody }: { requestBody?: any }): CancelablePromise<any>
```

<ParamField body="requestBody" type="any">
  Multipart form data containing the file to upload.
</ParamField>

The response includes a `data.hash` string — a unique identifier (UUID) you use as the `attachment` value in each multipart message part.

<Tip>
  Save the returned `data.hash` value immediately. You will need it when constructing the `parts` array for `sendMultipartMessage()`.
</Tip>

```typescript theme={null}
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`.

```typescript theme={null}
download({ guid }: { guid: string }): CancelablePromise<any>
```

<ParamField path="guid" type="string" required>
  The GUID of the attachment to download.
</ParamField>

<Note>
  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.
</Note>

```typescript theme={null}
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.

```typescript theme={null}
forceDownloadAttachment({ guid }: { guid: string }): CancelablePromise<any>
```

<ParamField path="guid" type="string" required>
  The GUID of the attachment to force-download.
</ParamField>

<Warning>
  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.
</Warning>

```typescript theme={null}
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.

```typescript theme={null}
getAttachmentLivePhoto({ guid }: { guid: string }): CancelablePromise<any>
```

<ParamField path="guid" type="string" required>
  The GUID of the attachment to retrieve the Live Photo for.
</ParamField>

<Note>
  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.
</Note>

```typescript theme={null}
const response = await client.attachments.getAttachmentLivePhoto({
  guid: 'attachment-guid-here',
});
// response contains the Live Photo .mov video data
```