Files on tickets
A ticket can carry two kinds of document:
- Attachments are links. You send a
urland anamewithPOST /ticketsand they are stored as given. Use them only for documents that are already public. - Files are stored by tkana, privately. You upload the bytes, and nobody can read them without a key that may read tickets. Use them for a customer’s own documents: an invoice, an ID, a photo of a damaged item.
A file never has a URL. That is the point of uploading it rather than linking it: a link works for anyone who has it, for as long as it exists, and a customer’s document must not be one forwarded email away from a stranger.
Uploading a file
Section titled “Uploading a file”Send the file as multipart/form-data with one part named file. The key needs
write:tickets.
- Size: at most 10 MB.
- Types: JPEG, PNG, GIF, WebP and HEIC images; PDF; plain text and CSV; Word (
.doc,.docx) and Excel (.xls,.xlsx); MP4, MP3 and Ogg. - A JPEG, PNG, GIF, WebP or PDF must really be one: its bytes are checked against the type you
declare, so a file declared
application/pdfthat is not a PDF is refused. Every other type, HEIC included, is accepted on its declared type alone. - A file is stored with the ticket’s customer’s data, so it is erased with them.
curl -s -X POST "$TKANA_API/tickets/$TICKET_ID/files" \ -H "Authorization: Bearer $TKANA_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -F "file=@invoice-1042.pdf;type=application/pdf"Do not set Content-Type yourself: curl and every HTTP library write the multipart boundary
into it, and a hand-written header without one cannot be parsed.
You get 201 with the stored file:
{ "id": "6f1c2a4e-8d0b-4b8e-9a51-1c3f0f6f2b7d", "name": "invoice-1042.pdf", "type": "application/pdf", "size": 48213}name is the part’s filename and type is the part’s media type. The file appears at once
on the ticket in the tkana portal, where the team works it.
Send an Idempotency-Key: a retried upload without one stores the file twice. See
idempotency.
When an upload is refused
Section titled “When an upload is refused”| Code | Status | What to do |
|---|---|---|
insufficient_scope |
403 |
The key lacks write:tickets. An owner can widen it in the portal. |
not_found |
404 |
No ticket with that id in this organization. |
payload_too_large |
413 |
The file is over 10 MB. |
validation_failed |
422 |
No file part, an empty file, a type tickets do not accept, or a JPEG, PNG, GIF, WebP or PDF whose bytes are not one. errors names file and detail says which. |
A refused upload stores nothing.
Listing a ticket’s files
Section titled “Listing a ticket’s files”Every ticket response carries files, in the order they were added, beside attachments:
{ "id": "0d6a…", "subject": "Refund for order 1042", "attachments": [], "files": [ { "id": "6f1c2a4e-8d0b-4b8e-9a51-1c3f0f6f2b7d", "name": "invoice-1042.pdf", "type": "application/pdf", "size": 48213 } ]}files also lists what staff uploaded in the portal, and what the customer sent over
WhatsApp with their request when the AI agent filed the ticket from that conversation. All of
them are downloaded the same way. For a customer’s WhatsApp file, type and size are null
when WhatsApp did not report them.
Downloading a file
Section titled “Downloading a file”curl -s "$TKANA_API/tickets/$TICKET_ID/files/$FILE_ID" \ -H "Authorization: Bearer $TKANA_KEY" \ -o invoice-1042.pdfThe response is the file itself, with its Content-Type and a Content-Disposition naming
it. The key needs read:tickets; each download is checked against
the key, so revoking a key or removing the scope stops it at once.
A file that is no longer stored answers 404.