Files and attachments
Customers can send photos and documents in a conversation, the agent reads them, and your team can send files back. A customer can send a photo of a damaged parcel and get an answer about it, or a PDF invoice and get a question about it answered from its text.
Where files can be sent
| Who | Where | How |
|---|---|---|
| Customers | Website chat | The paperclip next to the message box, in both the bubble and the chat box style. |
| Customers | Telegram | As a photo or as a document. The caption becomes the message text. |
| Customers | Your own app | Through the Sessions API: upload the file into the session, then send a message with its id. See API overview. |
| Your team | Inbox | The paperclip in the composer, or drag and drop, after you Take over the conversation. See Human handoff. |
| You, testing | Test panel | The same paperclip, while you play the customer. Editors and up. See Testing. |
The agent itself doesn't create or send files. It reads what customers send and answers in text. Files go to customers only when a person on your team attaches them.
Supported files
| Kind | Types |
|---|---|
| Images | JPEG, PNG, WebP, GIF |
| Documents | PDF, plain text (TXT), Markdown (MD), CSV |
Peki decides a file's type from its first bytes, never from its name or what the browser claims. A PNG renamed to .pdf is stored as a PNG; a file that isn't one of the types above is refused, whatever it is called. SVG and HTML are never accepted, and neither is a text file with web page markup or scripts in it.
The stored name always ends in the real type's extension. For example, invoice.html that turns out to be plain text is stored as invoice.txt.
Voice messages, audio, video, stickers and animations aren't supported. On Telegram the customer gets a short reply in their language that the bot can't open that kind of file yet; nothing is stored.
Limits
| Limit | Value |
|---|---|
| Size per file | 10 MB |
| Files per message | 5 |
| Files per conversation | 30 |
| Website chat uploads per visitor | 20 files per hour |
| Text read from one document | 20,000 characters |
| Recent customer messages whose files go to the model | 6 |
| Time to send an uploaded file | 24 hours |
When a conversation reaches 30 files, the customer has to start a new conversation to send more: New conversation in the website chat, /new on Telegram.
Uploads are checked twice: in the browser before any bytes leave (size and count, then the type from the first bytes), and again on the server.
Errors customers can see
The website chat, the Inbox and the Test panel show these in the viewer's language. Through the API they come as an error with a code.
| Code | Message (English) | What to do |
|---|---|---|
file_type | Send a photo (JPEG, PNG, WebP, GIF), a PDF or a text file (TXT, MD, CSV). | Convert the file, for example export a Word file as PDF. |
file_size | Files can be up to 10 MB. | Compress or split the file. |
file_count | Up to 5 files per message. | Send the rest in another message. |
conversation_full | This conversation has reached its 30-file limit. Start a new conversation to send more. | Start a new conversation. |
file_rate | Too many files at once. Please try again later. | Wait and try again. |
file_taken | This file was already sent. Please attach it again. | Attach the file again. |
file_missing | This file is no longer available. Please attach it again. | Attach the file again. |
On Telegram, the bot answers in the customer's language instead, for example "That file is too big: files can be up to 10 MB." or "This conversation already has 30 files. Send /new to start a new one."
How the agent reads attachments
On every reply, the agent gets the files of the last 6 customer messages that had files, oldest first, framed as data, never as instructions. Files sent earlier than that stay in the conversation by name only, so a long chat doesn't resend every photo.
Images
Images go to the model as pictures, but only if the model can read images. In the model picker, these models are marked Reads images. With another model, the agent gets a note that an image was sent, with its name, and can't see what is in it.
Before an image goes to the model, Peki takes its first frame (for a GIF), turns it upright, shrinks it to fit within 1568 × 1568 pixels, and converts it to JPEG. The file you see in the Inbox is the original.
If your customers will send photos (damaged products, a rash, a broken part), choose a model marked Reads images as the agent's first model. See Model and behavior.
Documents
For PDF, TXT, Markdown and CSV files, Peki extracts the text once, when the file is uploaded, and gives it to the agent:
- up to 20,000 characters per file; a longer text is cut, and the agent is told where;
- marked as file content, which is data and not instructions, so a document can't change how your agent behaves;
- with personal data hidden as placeholders, the same as in messages, when the personal data guardrail is on.
PDFs are read in the background. If the customer's message arrives before reading is done, the reply waits up to 20 seconds for it. After that, the agent is told the file is still being read.
A scanned PDF that contains only pictures of pages has no text to read. The agent is told the file has no readable text.
Images can't be masked the way text is. A photo of an ID card reaches the model as it is. See Data and privacy.
Seeing what the agent got
Open Why? under an agent reply in the Inbox or Test panel. The files line lists each file and how it was given to the model: as an image, as text it read, or as a note only (for example "not shown to this model"). See Inbox.
Files your team sends
After you take over a conversation in the Inbox:
- Click the paperclip, or drag files onto the conversation. Each file starts uploading straight away.
- Wait until the files are uploaded, then write a message if you want one. A reply can be files only.
- Send.
How the customer receives them:
| Channel | Delivery |
|---|---|
| Website chat | Photos as thumbnails, other files as chips. The visitor taps to open a photo or save a file. |
| Telegram | Photos as Telegram photos, other files as documents. A photo Telegram won't take as a photo (because of its size or proportions) goes as a document. If you send one file with a short message (up to 1,024 characters), the message becomes its caption; otherwise the message goes first, then the files. |
| API | Listed on the message as attachments, with id, name, type and size. |
You can only attach files you uploaded yourself in this conversation. A customer's file can't be sent back out as yours.
Where files show
There is no separate file library in Peki. Files live where they were sent:
- In the Inbox and Test panel, on the message they came with: photos as thumbnails, documents as chips you can open or download.
- On record pages, when a table has a
filefield and the agent saved a customer's file there, or a teammate uploaded one. A record keeps its own copy. See Records. - In Knowledge, for documents you added as sources. Knowledge accepts documents only, not images. See Knowledge.
- In the Copilot, for files you attached while building. See Working with Copilot.
Opening a file: images open in the browser; every other type downloads, so nothing in a file can run in your browser. Members and API keys of the workspace can read its files; a website chat visitor can only read the files of their own conversations.
Retention
| What | How long it is kept |
|---|---|
| A file sent in a message | As long as the conversation exists. |
| A file uploaded but never sent | Deleted after 24 hours, and can't be sent after that. |
| A record's copy of a file | As long as the record exists. Deleting the conversation doesn't remove it. |
| Everything of an agent | Deleted when you delete the agent. |
| Everything in a workspace | Deleted when you delete the workspace. |
Files are stored privately. They are never public, and every read goes through Peki, which checks who is asking. See Data and privacy.
Troubleshooting
| Problem | Why, and what to do |
|---|---|
| The agent says it can't see the photo | The agent's model doesn't read images. Pick a model marked Reads images. |
| The agent ignores most of a long PDF | Only the first 20,000 characters are read. Send the relevant pages, or put long reference documents in Knowledge instead. |
| The agent says a PDF has no readable text | It's a scan. Send the original PDF, or a photo of the page with a model that reads images. |
| A Telegram file was refused as too big | Files can be up to 10 MB. |
| A Telegram voice message got "I can't open this kind of file yet" | Voice, audio and video aren't supported. Ask the customer to write. |
| There is no paperclip in the Inbox | The composer, with its paperclip, appears only after you take over the conversation. |
| The paperclip is greyed out in the website chat | 5 files are already attached to the next message, or the chat isn't available (the agent isn't published). |