Files and attachments
Use this reference with the complete developer tour and Go types. The example at the end runs after the tour setup.
Attachments
Section titled “Attachments”List the files currently visible in a conversation.
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. Input/output fields are in the types reference.
StageAttachment
Section titled “StageAttachment”Upload a private draft before creating its message, request, chat or batch.
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. Input/output fields are in the types reference.
UploadAttachment
Section titled “UploadAttachment”Upload a file into an already authorized conversation.
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. Input/output fields are in the types reference.
DownloadAttachment
Section titled “DownloadAttachment”Download the bytes of a currently visible attachment.
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. Input/output fields are in the types reference.
Example
Section titled “Example”Run this region after the shared setup. Assertions check the returned data; the full tour is a runnable program.
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)