Skip to content

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.

{
"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.

Add downloadPath to your API base URL and call it with your key. The key needs read:conversations.

Terminal window
curl -s "$TKANA_API/conversations/$CONVERSATION_ID/messages/$MESSAGE_ID/media/0" \
-H "Authorization: Bearer $TKANA_KEY" \
-o invoice-1042.pdf

The 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.

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.