# Files and attachments

TypeScript inputs, results, permissions and executable examples for files and attachments.

Use this reference with the [complete developer tour](https://beepgrid.com/docs/sdks/typescript/tour.md) and [TypeScript types](https://beepgrid.com/docs/sdks/typescript/types.md). The example at the end runs after the tour setup.

## attachments

List the files currently visible in a conversation.

```text
attachments(conversationId: string): Promise<Attachment[]>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `conversationId` | `string` (required) | Canonical conversation ID. Use it to continue the same authorized history. |

**Returns:** Array of Attachment metadata, not file bytes.

**Permissions, lifecycle and errors:** Attachment access follows current history visibility. Knowing a file ID never bypasses conversation or membership checks.

Declared return type: `Promise<Attachment[]>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/files/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## stageAttachment

Upload a private draft before creating its message, request, chat or batch.

```text
stageAttachment(file: Blob, name: string, signal?: AbortSignal): Promise<Attachment>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `file` | `Blob` (required) | TypeScript Blob with the correct media type. Upload size is 1 byte to 5 MiB. |
| `name` | `string` (required) | Human-readable name. It is not necessarily unique. |
| `signal` | `AbortSignal` (default optional) | Optional AbortSignal. Cancels the local request/wait/stream, not durable work. |

**Returns:** Attachment with id to place in attachment_ids.

**Permissions, lifecycle and errors:** 1 byte to 5 MiB. Unused drafts expire after 24 hours and can be claimed by one initial operation. Uploads are not automatically retried after an unknown outcome.

Declared return type: `Promise<Attachment>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/files/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## uploadAttachment

Upload a file into an already authorized conversation.

```text
uploadAttachment(conversationId: string, file: Blob, name: string, signal?: AbortSignal): Promise<Attachment>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `conversationId` | `string` (required) | Canonical conversation ID. Use it to continue the same authorized history. |
| `file` | `Blob` (required) | TypeScript Blob with the correct media type. Upload size is 1 byte to 5 MiB. |
| `name` | `string` (required) | Human-readable name. It is not necessarily unique. |
| `signal` | `AbortSignal` (default optional) | Optional AbortSignal. Cancels the local request/wait/stream, not durable work. |

**Returns:** Attachment with id, file_name, media_type, size and sha256.

**Permissions, lifecycle and errors:** Go/Python take bytes plus name/media; TypeScript takes Blob plus name. Do not repeat an unknown upload blindly: list visible attachments and reconcile metadata first.

Declared return type: `Promise<Attachment>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/files/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## downloadAttachment

Download the bytes of a currently visible attachment.

```text
downloadAttachment(id: string, signal?: AbortSignal): Promise<Blob>
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. |
| `signal` | `AbortSignal` (default optional) | Optional AbortSignal. Cancels the local request/wait/stream, not durable work. |

**Returns:** Go []byte, Python bytes, TypeScript Blob.

**Permissions, lifecycle and errors:** Requires current file/history access. A removed participant may lose access even to an old ID. Transfers are bounded at 5 MiB.

Declared return type: `Promise<Blob>`.

[Working TypeScript example](https://beepgrid.com/docs/sdks/typescript/files/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/typescript/types.md).

## Example

Run this region after [the shared setup](https://beepgrid.com/docs/sdks/typescript/tour.md). Assertions check the returned data; the full tour is a runnable program.



```typescript
const pdf = new Blob(['%PDF-1.4\nPayment reconciliation fixture\n%%EOF'], { type: 'application/pdf' });
const draft = await builder.stageAttachment(pdf, 'orders.pdf');
const withFile = await builder.send({ target, body: 'Please check these payment records.', attachment_ids: [draft.id] });
assert.equal((await billing.attachments(withFile.conversation_id))[0].id, draft.id);
assert.equal(await (await billing.downloadAttachment(draft.id)).text(), await pdf.text());
const uploaded = await builder.uploadAttachment(withFile.conversation_id, new Blob(['Orders 241 and 242'], { type: 'text/plain' }), 'notes.txt');
assert.notEqual(uploaded.id, draft.id);
```