Files in conversations
A message can carry files: a photo of a damaged item, a PDF invoice, a voice note. Every
message lists its files in media, in the order they were sent. A message with no files has
an empty list.
You get the same list from GET /conversations/{id}/messages and from the
message.received and message.sent webhooks.
What a file looks like
Section titled “What a file looks like”{ "id": "7a2b…", "conversationId": "1f0c…", "senderType": "customer", "messageType": "media", "content": "", "media": [ { "index": 0, "type": "document", "mimeType": "application/pdf", "fileName": "invoice-1042.pdf", "sizeBytes": 48213, "caption": "this is the one I paid", "status": "stored", "url": null, "downloadPath": "/conversations/1f0c…/messages/7a2b…/media/0" } ]}| Field | Meaning |
|---|---|
type |
image, document, video, audio (a voice note) or sticker. |
mimeType, fileName, sizeBytes, caption |
As WhatsApp reported them. Each is null when WhatsApp did not send it. |
status |
pending while tkana saves a file the customer just sent, stored once you can download it, unavailable when WhatsApp withheld the file or it has been erased. |
downloadPath |
Where to download a file the customer sent. null on a file your team or the AI agent sent, and on an unavailable file. |
url |
The public address of a file your team or the AI agent sent. null on a file the customer sent. |
A voice note’s transcript is the message’s content.
Downloading a file the customer sent
Section titled “Downloading a file the customer sent”Add downloadPath to your API base URL and call it with your key. The key needs
read:conversations.
curl -s "$TKANA_API/conversations/$CONVERSATION_ID/messages/$MESSAGE_ID/media/0" \ -H "Authorization: Bearer $TKANA_KEY" \ -o invoice-1042.pdfThe response is the file itself, with its Content-Type and a Content-Disposition naming
it. A file sent without a name is named after its type, for example image-1.jpg.
| Code | Status | What to do |
|---|---|---|
insufficient_scope |
403 |
The key lacks read:conversations. An owner can widen it in the portal. |
not_found |
404 |
No such conversation, message or file, or the file is unavailable or erased. |
media_not_ready |
409 |
tkana is still saving the file. Try again after a few seconds. |
A customer’s file never has a URL. Each download is checked against the key, so revoking the key or removing the scope stops it at once. If your system shows the file to its own users later, save the bytes on your side.
Files your team sent
Section titled “Files your team sent”A file sent from the tkana portal or by the AI agent is already at a public address, which
is where WhatsApp fetched it from. Read it from url. It has no downloadPath.