Skip to main content
POST
Get a presigned URL to upload a message attachment

Overview

Attachments are not uploaded through this API directly. Instead you exchange the file’s metadata for a short-lived, pre-signed Amazon S3 upload, push the file straight to S3, and then reference the returned URL when you send a message. This keeps large files off our servers and lets uploads scale. The flow has three steps:
1

Request a pre-signed upload

Call this endpoint with the file’s mimeType, size and a fileName. You get back an uploadUrl, a set of fields, and the final fileUrl. The conversation’s chatbot is resolved server-side from the conversationId — you don’t pass a chatbotId.
2

Upload the file to S3

Send a multipart/form-data POST to uploadUrl containing every entry in fields first, then the file last.
3

Send the message

Call Send message or Reply to a conversation with an attachments array that references the fileUrl and metadata.
The conversation must already exist. The conversationId is validated against your workspace, so you can only upload into your own conversations.

Step 1 — Request a pre-signed upload

Response:
The pre-signed upload expires in 5 minutes (300 seconds). Upload the file promptly, or request a new one.

Step 2 — Upload the file to S3

POST the file to uploadUrl as multipart/form-data. Append every key from fields in order, then append the file field last — S3 ignores any field that comes after file.
A successful upload returns 204 No Content. The Content-Type you send must match the Content-Type in fields, and the file size must be within the per-category limit — S3 rejects the upload otherwise, even if step 1 succeeded.
In a browser, build a FormData object: append each fields entry with formData.append(key, value), then formData.append('file', file) last, and fetch(uploadUrl, { method: 'POST', body: formData }).

Step 3 — Send the message with the attachment

Reference the fileUrl and metadata in the attachments array. The message type is resolved automatically (a single image → IMAGE, anything else → FILE).
Every attachment is re-validated server-side before it is stored; invalid entries are dropped. The stored attachment is returned with an id and a resolved category (image | video | audio | doc | text).

Allowed types and size limits

Only the MIME types below are accepted. Anything else — including image/svg+xml, text/html, and JavaScript types — is rejected for security.

Errors

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

conversationId
string
required

Unique identifier of the conversation the attachment belongs to

Example:

"chat_1234567890"

Body

application/json
fileName
string
required
Example:

"report.pdf"

mimeType
string
required
Example:

"application/pdf"

size
integer
required

File size in bytes

Response

Presigned upload URL

status
string
Example:

"success"

data
object