# Files and attachments

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

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

## Attachments

List the files currently visible in a conversation.

```text
func (c *Client) Attachments(ctx context.Context, conversationID string) ([]Attachment, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `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.

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

## StageAttachment

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

```text
func (c *Client) StageAttachment(ctx context.Context, name, media string, data []byte) (Attachment, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `name` | `string` (required) | Human-readable name. It is not necessarily unique. |
| `media` | `string` (required) | Declared media type, for example application/pdf. |
| `data` | `[]byte` (required) | JSON request body for call/Do; raw bytes for Python/Go file upload. |

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

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

## UploadAttachment

Upload a file into an already authorized conversation.

```text
func (c *Client) UploadAttachment(ctx context.Context, conversationID, name, media string, data []byte) (Attachment, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `conversationID` | `string` (required) | Canonical conversation ID. Use it to continue the same authorized history. |
| `name` | `string` (required) | Human-readable name. It is not necessarily unique. |
| `media` | `string` (required) | Declared media type, for example application/pdf. |
| `data` | `[]byte` (required) | JSON request body for call/Do; raw bytes for Python/Go file upload. |

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

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

## DownloadAttachment

Download the bytes of a currently visible attachment.

```text
func (c *Client) DownloadAttachment(ctx context.Context, id string) ([]byte, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `id` | `string` (required) | Existing stable resource ID, returned by the corresponding create/read operation. |

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

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

## Example

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



```go
pdf := []byte("%PDF-1.4\nPayment reconciliation fixture\n%%EOF")
draft := must(builder.StageAttachment(ctx, "orders.pdf", "application/pdf", pdf))
withFile := must(builder.Send(ctx, beepgrid.SendInput{Target: target, Body: "Please check these payment records.", AttachmentIDs: []string{draft.ID}}, beepgrid.Key()))
check(must(billing.Attachments(ctx, withFile.ConversationID))[0].ID == draft.ID)
check(string(must(billing.DownloadAttachment(ctx, draft.ID))) == string(pdf))
check(must(builder.UploadAttachment(ctx, withFile.ConversationID, "notes.txt", "text/plain", []byte("Orders 241 and 242"))).ID != draft.ID)
```