Add file attachments to a support request
Section ID: Guide/jb17as5m7j#upload-and-download-files
A customer reporting a bug needs to send a recording and open it again when they return to the case. Build an attachment flow that uploads the recording, confirms it is stored, and retrieves a fresh download link whenever the customer opens it.
This recipe uses video.mp4 as an example. The same flow works for documents and other files. Your application owns the support request and associates it with Travila's returned fileId; Travila provides file storage, metadata and temporary upload/download URLs.
Before you start: use an authenticated application user, a backend credential kept off the browser, and a test file you are allowed to store. Create the /media folder through the folder recipe if your application needs a folder entry. Use the same user for every storage call in this recipe.
Build the upload interaction
Section ID: Guide/jb17as5m7j#uploading-files
When the customer selects a file, your application knows its name, content type and byte size. Keep the attachment in a pending state while the upload and registration finish. Only a registered file is ready to show as an attachment.
Use a pre-signed upload for new integrations, including small files. The file bytes go directly to the returned upload destination, while your backend handles the authenticated Travila requests. This avoids sending a base64 copy through your API request.
The flow has three stages: request an upload URL, send the file bytes, then register the uploaded file. Keep the returned file ID across those stages so an interrupted request can be checked without starting another attachment.
Upload and confirm the recording
Section ID: Guide/jb17as5m7j#pre-signed-upload-large-files
1. Request a destination for the selected file. Supply its actual byte size. This example declares a 50 MiB recording; use the size of your own file. The upload URL expires after the requested period.
Request example: Generate a pre-signed upload URL. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
Travila returns the file ID to keep with the pending attachment, the upload URL and the headers your uploader must send:
Response example: Generate a pre-signed upload URL. Example identifiers and values are illustrative; substitute authorized values.
Check that the upload finished before registering it. If a response is lost, keep the same file reference while recovering the attachment.
2. Send the selected file to that URL. Use the returned URL and every requiredHeaders value unchanged. The example below shows the values from the response above; your application must use its own response.
Provider-specific upload illustration: first use the upload-URL contract. Use the returned URL and required headers unchanged; upload the file bytes as the binary body, not JSON or protobuf. The example uses a PUT of video.mp4, Content-Type video/mp4, and a provider-required x-goog-content-length-range of 0,52428800. Its storage.googleapis.com bucket URL is a placeholder, not an issued upload target. Use the provider, URL and headers returned for your upload; these example values are not an upload target.
3. Register the uploaded file. Use the same ID, folder and name to make it available for listing and download:
Request example: Register a file uploaded via pre-signed URL. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
After registration succeeds, save the fileId on your application's support request and mark the attachment ready. The customer can leave and return to the case without uploading it again. If registration returns 404, the object is not yet available; check the upload before registering again.
Exact request and response fields: upload URL and registration.
Let the customer reopen the attachment
Section ID: Guide/jb17as5m7j#downloading-files
When the customer opens the case, load the saved fileId from your application record. Authenticate that same user and request a fresh download URL:
Request example: Generate a pre-signed download URL. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
Response example: Generate a pre-signed download URL. Example identifiers and values are illustrative; substitute authorized values.
Use the returned URL to open or download the recording. The response also provides its name, type and size for your attachment row. The completed feature lets the customer reopen the stored recording after a page reload; it does not depend on keeping the original upload URL.
To offer a download with a chosen filename, use the operation's responseContentDisposition field, for example:
Request example: Generate a pre-signed download URL. Example identifiers and values are illustrative; substitute authorized values.
Request a URL when it is needed and keep it out of public logs or messages. Its expiry limits the link's lifetime; anyone who possesses a still-valid URL can use it. Do not treat the URL as the permanent attachment record. See the download reference for the exact contract.
Show several attachments on the case
Section ID: Guide/jb17as5m7j#many-urls-at-once
For a case with several attachments, use the saved file IDs to request download links in a batch of 1–50 files. This prepares the attachment list without a separate request for every link:
Request example: Generate pre-signed download URLs for multiple files. Example identifiers and values are illustrative; substitute authorized values.
Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.
Response example: Generate pre-signed download URLs for multiple files. Example identifiers and values are illustrative; substitute authorized values.
Render each result independently. Show a link only when success is true and a usable URL is present. A missing success flag means false; show an unavailable attachment for that entry while leaving successful attachments usable. Match the result by fileId, not by assuming the whole batch succeeded.
The batch can return different outcomes even when its HTTP request succeeds. Use the batch reference for all fields.
Recover an attachment that cannot be opened
Section ID: Guide/jb17as5m7j#file-references-and-expiry
| Customer sees | Application recovery |
|---|---|
| Upload did not finish | Keep the attachment pending. Check the transfer before attempting registration; a URL response alone did not store the file. |
| Registration response was lost | Register the same file ID again and use its existing result. |
| Download link expired | Request a new authorized link for the saved file ID. Do not ask the customer to upload the file again solely because a link expired. |
| File is no longer available or access is denied | Show that attachment as unavailable and keep other attachments usable. A saved ID does not guarantee permanent retention or access. |
| An assistant cannot read a required attachment | Explain that the file could not be used; do not present an answer as if it included that file. See conversation attachments. |
The supplied contentType is metadata. It does not independently verify the bytes or establish that a file is safe to display. Apply the file handling rules your application needs before rendering customer content.
Move an existing inline uploader to this flow
Section ID: Guide/jb17as5m7j#inline-upload-small-files
If your application already sends base64 content to upload-file, replace that path with the three stages above and keep associating the resulting file ID with the same application record. Inline upload is deprecated; it is not the recommended path for a new attachment feature. Its exact legacy contract remains in the inline upload reference.
Complete one upload and reopen it through a fresh download link before switching the rest of your application. Existing registered files can continue to be retrieved by their IDs.
Document ID: Guide/jb17as5m7j