Files and attachments
Use this reference with the complete developer tour and TypeScript types. The example at the end runs after the tour setup.
attachments
Section titled “attachments”List the files currently visible in a conversation.
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. Input/output fields are in the types reference.
stageAttachment
Section titled “stageAttachment”Upload a private draft before creating its message, request, chat or batch.
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. Input/output fields are in the types reference.
uploadAttachment
Section titled “uploadAttachment”Upload a file into an already authorized conversation.
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. Input/output fields are in the types reference.
downloadAttachment
Section titled “downloadAttachment”Download the bytes of a currently visible attachment.
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. 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.
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);