Files

Get file upload URL

Generates a presigned URL for uploading a file. After uploading, use the returned file_id as an attachment ID in messages.

POST /v1/custom/:integration_id/sessions/:session_id/files/upload-url

Path parameters

Parameter	Type	Required	Description
integration_id	UUID	Yes	Your custom integration ID.
session_id	UUID	Yes	The session ID.

Request body

{
  "filename": "receipt.pdf",
  "content_type": "application/pdf"
}

Field	Type	Required	Description
filename	string	Yes	Original filename.
content_type	string	Yes	MIME type of the file (e.g., image/png, application/pdf).

Response — 200 OK

{
  "request_id": "550e8400-e29b-41d4-a716-446655440009",
  "upload_url": "https://storage.example.com/presigned-upload-url",
  "file_id": "file-abc123"
}

Field	Type	Description
request_id	string	Unique identifier for this request.
upload_url	string	Presigned URL to upload the file via HTTP PUT.
file_id	string	File identifier to use in message attachments.

Upload the file with a single PUT to upload_url, sending the same Content-Type you declared in the request — the content type is part of the signature, so a mismatch is rejected. The URL expires 5 minutes after it is issued, so request it at the point of upload rather than ahead of time.

Example

curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @receipt.pdf

---

Get file download URL

Generates a presigned URL for downloading a previously uploaded file.

POST /v1/custom/:integration_id/sessions/:session_id/files/download-url

Path parameters

Parameter	Type	Required	Description
integration_id	UUID	Yes	Your custom integration ID.
session_id	UUID	Yes	The session ID.

Request body

{
  "file_id": "file-abc123"
}

Field	Type	Required	Description
file_id	string	Yes	The file identifier from a previous upload or webhook attachment.

Response — 200 OK

{
  "request_id": "550e8400-e29b-41d4-a716-446655440010",
  "download_url": "https://storage.example.com/presigned-download-url",
  "file_id": "file-abc123"
}

Field	Type	Description
request_id	string	Unique identifier for this request.
download_url	string	Presigned URL to download the file via HTTP GET.
file_id	string	The file identifier, echoed back from the request.

The URL expires 30 minutes after it is issued. Request a new one rather than storing it.