Get attachment by message ID and attachment ID (inbound or outbound)
/v1/messages/{message_id}/attachments/{id}org.permission.attachment.readorg.user.attachment.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Retrieves attachments based on the unique ID of the attachment for a specific message ID.
Attachments
An attachment is a file, such as an image, PDF or recording, attached to a message, note, draft, forward or custom object comment. Kustomer stores a record describing the file, and you upload or download the bytes through short-lived signed URLs.
Files show up throughout the agent desktop: a photo a customer sent in chat, a PDF on an outbound email, a screenshot in an internal note. In the API, each file is an attachment record with name, contentType and contentLength (in bytes), plus a link to the object that carries it. The file's bytes never travel through the regular API: you upload them to, and download them from, temporary signed URLs that Kustomer hands you. Attachments on inbound messages are created by Kustomer when the message arrives.
Two upload styles
Which flow you use depends on what the file is going on.
| Attaching to | How |
|---|---|
| A message or note | Create the record with POST /v1/attachments, upload the file to meta.upload.url as a multipart form with every field from meta.upload.fields and the file last, then list the attachment in the message or note's attachments. |
| A draft or forward | Create the attachment under the draft or forward. Its links.related is a signed URL that you upload the file to with a single PUT. |
Upload immediately, because the upload URL expires; a record whose upload never completes stays uploaded: false. With POST /v1/attachments you can instead register a file you host by passing externalUrl (absolute https://, no credentials). Kustomer then stores only the link and never fetches or deletes the file. Add renderMode: "metadata_only" to keep that URL from ever being returned, so agents see only the file name and size. The attachments guide walks through every step with code.
Reading files
The record's links.related is a temporary download URL. Download the file promptly and don't store the URL. GET /v1/attachments/{id} covers outbound files only, so read files that customers sent through their message, which works for both directions. To find every file in a thread, use GET /v1/conversations/{id}/attachments.
Comments are internal notes on custom objects. Their files are set through the comment's attachments field, and the comment attachment endpoints read or remove them. A redacted comment attachment returns 410 Gone when you request it with redirect=true. Attachments removed through message redaction are marked redacted: true.
Which endpoint to use
| To | Call |
|---|---|
| Create a file record for a message or note | POST /v1/attachments |
| Read, rename or mark a file redacted | GET or PUT /v1/attachments/{id} |
| Download a message's file | GET /v1/messages/{message_id}/attachments/{id} |
| Add, list, read or remove a draft's files | POST or GET /v1/drafts/{id}/attachments, GET or DELETE /v1/drafts/{id}/attachments/{attachmentId} |
| Add, list, read or remove a forward's files | POST or GET /v1/forwards/{id}/attachments, GET or DELETE /v1/forwards/{id}/attachments/{attachmentId} |
| List, read or remove a comment's files | GET or DELETE /v1/comments/{id}/attachments, GET or DELETE /v1/comments/{id}/attachments/{attachmentId} |
Set contentType accurately, because the agent desktop uses it to preview images and PDFs, and make contentLength match the file you upload. PUT /v1/attachments/{id} creates the record if it doesn't exist and needs message update permission. WhatsApp drafts accept only certain media types; see Create draft for customer.
Path parameters
Message ID.
"60254e3ec413ae00571e3c97"Attachment ID.
"5a4d1a8a6d92880012ad2923"Responses
OK