Create Attachment Upload URL

Beta
POST/v1/messaging/conversations/{id}/attachments/actions/upload-url

Idempotent with Idempotency-Key header. Learn more

Creates a short-lived URL for uploading a chat attachment straight to object storage.

Upload the file to the returned URL, then send a message in the same conversation carrying the returned key as an attachment — the file only becomes part of the conversation at that point, and an upload that is never sent is discarded automatically. You must be an active participant of the conversation to stage an upload for it.

Permissions requiredValues:messaging:create
The role behind your API key or agent must grant every one of these permissions.
idstring

Conversation ID the attachment will be sent in.

The upload can only be attached to a message in this conversation.

include[]optional arrayenumValues:attachmentattachment.resource

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

filenamestring

The original filename of the file to upload.

content_typeoptional string

The MIME content type of the file.

The file must then be uploaded with this same content type, or object storage rejects it. It also decides how the attachment preview returned here is classified: image/… becomes an inline image, anything else a file.

objectstringenumValues:attachment_upload_target

Resource type identifier.

attachmentmessage_attachmentExpandablenullable

A preview of the attachment the file becomes once it is sent with a message.

idstring

Attachment ID.

objectstringenumValues:message_attachment

Resource type identifier.

kindstringenumValues:fileimagelink

The kind of attachment, which determines how it is stored and which of the fields below are populated.

  • file: an uploaded non-image file.
  • image: an uploaded image.
  • link: an external URL reference, with no stored file.
  • resource: a reference to an in-app resource, such as an order.
filenamestringnullable

The filename the attachment was uploaded under.

Carried only by file and image attachments.

content_typestringnullable

The MIME type of the uploaded content.

Carried only by file and image attachments.

size_bytesintegernullable

The size of the uploaded content in bytes.

Carried only by file and image attachments, and only when the sender supplied it with the message.

urlstringnullable

Where to fetch the attachment: a signed download URL for file and image attachments, or the target address for link attachments.

Download URLs are signed for one hour and regenerated each time the message is read, so follow the URL promptly instead of persisting it. resource attachments have no URL — use resource to resolve them.

resourceentityExpandablenullable

The in-app record a resource attachment points to, such as a sales order.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

created_atstring (date-time)

Creation timestamp.

upload_urlstring

The presigned URL to PUT the file to.

Send the file with the same content type used to mint the target, or the upload is rejected.

s3_keystring

The object-storage key identifying the uploaded file.

Pass it back as an attachment's s3_key when sending a message. It is bound to the conversation it was minted for and cannot be attached in another one.

expires_atstring (date-time)

When the upload URL stops working.

Targets are short-lived (about fifteen minutes); request a new one if the upload has not finished by then.

Responses

200

Successful response for Create Attachment Upload URL